API-04 design rule herschreven op basis van issue #419

[mrtn78]

Resolves Geonovum/KP-APIs#419

API-04 design rule herschreven op basis van issue #419

Kopie van het issue:
Originele bericht van Provincie Zuid-Holland:

API-04: Define interfaces in Dutch unless there is an official English glossary available
Dit is niet te hanteren in een situatie waarin die glossary er nog niet is. Twee situaties:

• een open source ontwikkeltraject waarin je nog niet beschikt over een engelstalige glossary maar toch de code internationaal wilt delen om de community zo groot mogelijk te maken. Engels is dan de te hanteren standaardtaal.
• interfaces met een COTS toepassing. De leverancier is internationaal georiënteerd en hanteert Engels als voertaal.

Interpretatie vanuit Logius voor aanpassing van de ADR:

• we gaan duidelijk onderscheid maken tussen het hergebruik van bestaande glossary/schema en het ontwikkelen van een eigen (nieuwe) glossary
• toevoegen dat samenwerking met COTS (Commercial Off The Shelf ) software leveranciers ook een reden kan zijn om engels te hanteren.

[TheBonheurs]

• Waarom is er gekozen voor de term Glossary? Zou Specification niet een betere term zijn?
• Zijn het eigenlijk niet gewoon naming conventions? Zal ik deze term in verwerken?
• De structuur van de zin "define in Dutch unless English exists" matcht niet zo lekker met de achterliggende intentie volgens mij. Wij zijn voorstander van zoveel mogelijk Engelse definities vanwege interoperabiliteit met de bestaande API dev community, zie bv. Google API design docs. Ik zou dan de regel zo formuleren → "define in English/adhere to English conventions unless there are none available. Fallback on dutch otherwise." Thoughts?

[mrtn78]

Aandachtspunten:

• official kan eruit.
• interfaces specifieker benoemen tot resources en attributes
• term Glossary blijft
• onderzoeken hoe dit samenhangt met de module naming conventions

[TheBonheurs]

API-Design-Rules/DesignRules.md

Line 470 in 09bab5b

In line with design rule <a href="#/core/interface-language">/core/interface-language</a>, the OAS document (e.g. descriptions and examples) SHOULD be written in Dutch. If relevant, you MAY refer to existing documentation written in English.

willen wij ook deze rule aanpassen?
dat was ook een opmerking van Hugo volgens mij, dat de OAS gewoon in engels kon blijven.

[TimvdLippe]

Dit voorstel is afgewezen in het TO. Als er hernieuwde interesse is, dan kunnen we de wijziging heroverwegen.