Filosofie

XSD documentatie is tradioneel een antwoord op de vraag "Wat is [element]", bijvoorbeeld "Wat is een vergadering?", bijna als een soort woordenboek definitie dus. Ik heb een andere filosofie gekozen; de documentatie is (meestal) een antwoord op "Wat voor informatie hoort in dit element?" of "Wat voor rol speelt dit" (dus iets meer "Hoe" ipv "Wat")

Dit omdat ik vermoed dat de meeste mensen wel weten wat een vergadering is, en omdat technische documentatie tegenwoordig juist meer op "Hoe" is gericht.

~Tradioneel bevat XSD documentatie geen witregels; ik ben qua formatting geïnspireerd door Google-stijl python docstrings. Door deze huisstijl aan te houden heb ik hier en daar misschien ook teveel informatie opgenomen; een van mijn voornaamste vragen is dan ook wat er qua informatie weg kan.~

Wat "blockers"

Vragen die we beantwoord moeten hebben voordat we dit kunnen mergen (zie hieronder voor een verdere uitleg):

[x] Wat moet er allemaal in de XSD documentatie blijven staan, en wat kan er naar de documentatie PDF?
[x] Moeten we line wrapping gebruiken?
[x] Werkwoords vormen in verleden tijd of niet?
[x] Houden we markup er in?
[x] Twee opties voor "Verwachte waarde:" blokjes

Wat moet er allemaal in de XSD documentatie blijven staan, en wat kan er naar de documentatie PDF?

Op dit moment staan voor elk element de volgende dingen gedocumenteerd:

korte proza beschrijving
~verwacht datatype~
voorbeeld waardes (waar ik het nodig vondt)
~relaties tussen elementen (though alleen in het geval van top-level elementen)~

De vraag is wat hiervan echt in de XSD zelf moet, en wat naar de toekomstige "documentatie PDF" kan.

"Verwachte waarde" voelt bijvoorbeeld als dubbele informatie, omdat dit al afleidbaar is uit type=. Misschien alsnog wel gebruiksvriendelijk om er in te houden, alhoewel deze keuze ook weer andere complexe keuzes met zich meebrengt (zie hieronder).
Zo nu en dan een voorbeeld van een verwachte waarde lijkt me goed om er in te houden; alhoewel dit misschien naar de proza beschrijving kan. Ik heb dan zoiets voor ogen:

<xsd:element name="volledigeNaam" type="xsd:string" minOccurs="0" maxOccurs="1">
    <xsd:annotation>
        <xsd:documentation>De volledige naam van de persoon, bijvoorbeeld 'Piet van der Berg'.</xsd:documentation>
    </xsd:annotation>
</xsd:element>
<xsd:element name="voornamen" type="xsd:string" minOccurs="0" maxOccurs="1">
    <xsd:annotation>
        <xsd:documentation>De voornaam of voornamen van de persoon. Bijvoorbeeld 'Anna Maria Sophia' of 'Jan'.</xsd:documentation>
    </xsd:annotation>
</xsd:element>

Dit is al een stuk korter, en zegt alsnog iets over "verwachte waarde" middels een voorbeeld.

~Relaties tussen elementen twijfel ik nog over. Omdat we nu een mild chaotische mix tussen nesten en verwijzing via IDs gebruiken is het niet altijd duidelijk waar iets moet komen. Wilmar liep hier bijvoorbeeld tegenaan toen hij een conversie maakte.~

<xsd:element name="aanwezigeDeelnemer" type="aanwezigeDeelnemerGegevens" minOccurs="0" maxOccurs="unbounded">
    <xsd:annotation>
        <xsd:documentation>
            Gegevens over een persoon die daadwerkelijk bij de vergadering aanwezig was.

            Relaties:
              - `isNatuurlijkPersoon` (`verwijzingGegevens`): verwijzing naar een `natuurlijkPersoon` element met contextuele informatie over de deelnemer
              - `neemtDeelAanVergadering` (`verwijzingGegevens`, optioneel): verwijzing naar de (deel)vergadering waarbij de deelnemer aanwezig was
              - `neemtDeelAanStemming` (`stemGegevens`, optioneel): gegevensgroep met informatie over wat deelnemer heeft gestemd tijdens een stemming
              - `spreektTijdensSpreekfragment` (`spreekfragmentGegevens`, optioneel): gegevensgroep met informatie over een spreekfragment
        </xsd:documentation>
    </xsd:annotation>
</xsd:element>

~Als je iets van een "Relaties:" blokje in de documentatie van top-level elementen houdt (tho misschien anders vormgegeven) dan zien gebruikers van de XSD misschien sneller dat ze info over spreekfragmenten onder aanwezigeDeelnemer kwijt kunnen.~

~Line wrapping~

EDIT: Door een aantal veranderingen zijn er nu al iets minder vaak lange regels. Daarom besloten (bijna) nergens harde line breaks toe te voegen.

Houden we markup in de XSD

Er zit nu best wel wat (markdown) markup in de XSD, zoals lijstes en backticks (`). Markdown-achtige markup in documentatie is gebruikelijk in de meeste programmeertalen; maar levert problemen op in de meest gebruikte LSP voor de XML taal (die overigens ook de documentatie popups genereerd in VS Code en Eclipse). Dat wil zeggen: de XML LSP snapt markdown niet echt, waardoor documentatie popups in je IDE/teksteditor er raar uitzien. HTML markup wordt wel ondersteunt, maar dat is slecht leesbaar voor mensen.

Ik wil nog een keer de discussie met deze LSP ontwikkelaars voortzetten om Markdown toch iets beter te ondersteunen. Maar buiten bovenstaand esthetische punt zijn er denk ik niet veel nadelen verbonden aan wat markup in de documentatie houden. iig lijstjes markup mag er wel in blijven naar mijn mening. Markup kan ook handig zijn als we PDF documentatie willen genereren uit XSD documentatie.

Verleden tijd

Ik heb de documentatie nu op veel plekken in de verledentijdsvorm opgesteld. Dit omdat een uitwissel/archiveer standaard bedoeld is voor vergaderingen die reeds hebben plaatsgevonden.

MDTO en de VNG gebruiken echter nergens verleden tijd. Is de verledentijdsvorm vermijden een goed idee?

~Hoe "Verwachte waarde:" blokje vormgeven~

Edit: punt vervalt, omdat deze blokjes zijn verwijderd.

wvanommeren commented 3 months ago

Wat moet er allemaal in de XSD documentatie blijven staan, en wat kan er naar de documentatie PDF? Ik denk dat al je voorbeelden wel in de xsd passen in korte(re) vorm en in uitgebreide vorm in de documentatie.pdf. Dan kan je altijd op de pdf terugslaan als je het niet helemaal begrijpt
Moeten we line wrapping gebruiken? Werkt dit wel met LSP? Ik ben altijd wel fan van line wrapping, al kan je je afvragen of je niet gewoon teveel tekst (die eigenlijk in de documentatie pdf thuishoort) op een regel bent aan het proppen als ze zo lang worden.
Werkwoords vormen in verleden tijd of niet? Ik heb hier niet echt een sterke mening over dus wmb is verleden tijd prima.
Houden we markup er in? Wat mij betreft leest dat wel het lekkerste weg voor mij want ik scroll een beetje door de xsd weg om hem te gebruiken. Ik denk dat de afweging moet zijn hoe wordt de documentatie het meest gelezen, via zo'n LSP of direct uit de xsd.
Hoe "Verwachte waarde:" blokje vormgeven: Ik zou zeggen hou het in de xsd kort. De gebruikers kennen neem ik aan de zoekfunctie en kunnen zo wel vinden wat er in de kinderen van een datatype hoort te staan. De uitgebreide variant kan in de documentatie pdf

rien333 commented 3 months ago

Met al je punten eens, heel erg bedankt voor je input! Ik had even iemand nodig die me hielp met keuzes maken.

Als we de XSD documentatie kort houden dan vervallen eigenlijk ook best veel van bovenstaande problemen, inclusief misschien de noodzaak van linewrapping.

Moeten we line wrapping gebruiken?

Werkt dit wel met LSP?

Yes, net getest ook. Hangt wel van de LSP implementatie af, uiteindelijk.

Maar degene die vrijwel iedereen nu gebruikt interpreteert alles als HTML code, waarin witregels betekenisloos zijn en dus gestripped worden tijdens de weergave. De enige manier om witregels toe te voegen aan LSP popups is met het daarvoor bestemde HTML element, </br>.