Als gebruiker/developer wil ik API documentatie eenvoudig kunnen doornemen

VNG-Realisatie / gemma-zaken

Samen ontwikkelen van API's voor Zaakgericht werken

https://vng-realisatie.github.io/gemma-zaken/

Other

41 stars 27 forks source link

Als gebruiker/developer wil ik API documentatie eenvoudig kunnen doornemen #80

Closed ehotting closed 6 years ago

ehotting commented 6 years ago

.... zodat ik snel alle informatie heb die ik nodig heb.

Definition of done

[x] Eerste versie specificatie is gepubliceerd leesbaar op een publieke website
[x] Bijbehorende functionele documentatie is daar ook te vinden
[x] Wijzigingen in specificaties op Github worden automatisch gepubliceerd

Acceptatiecriteria

[ ] Developers worden happy van de wijze van navigatie en presentatie
[ ] Niet-developers worden happy van de wijze van navigatie en presentatie
[x] Het geheel volgt design Common Ground
[x] Website op eigen hosting (geen SaaS)
[x] Open Source

Taken

[x] Regelen ReDoc (of geschikt alternatief) [@joeribekker]
[x] Toepassen design framework CG [@joeribekker]
[x] Functionele documentatie onderbrengen in oplossing [@joeribekker]
[x] Mechanisme voor automatisch doorvoeren wijzigingen [@joeribekker]

michielverhoef commented 6 years ago

VNG-Realisatie heeft een betaald account op SwaggerHub welke sinds enige tijd (oktober 2017) OAS 3.0 ondersteunt: https://swaggerhub.com/blog/news/openapi-3-0-swaggerhub-support/. Mogelijk kan dit een eenvoudige, snelle oplossing zijn?

michielverhoef commented 6 years ago

Definition of done • [ ] Een publicatie mechanisme om een Open API Specificatie (v.3.0) Human Readable te kunnen publiceren • [ ] Een specificatie kan leesbaar gepubliceerd worden

Taken • [ ] Een technisch mechanisme realiseren om het publiceren van de API te ondersteunen [?] • [ ] De styling/user experience zodanig maken dat een developer snel en goed kan vinden wat hij nodig heeft [?] • [ ] Het publicatie mechanisme voor een zoekmachine goed doorzoekbaar maken zodat een developer ook van buiten de informatie die hij zoekt goed kan vinden [?]

joeribekker commented 6 years ago

Ik ben het niet eens met de (enige) taak die hier staat. Ook is de DoD niet van toepassing hier maar meer op de daadwerkelijke API resources en niet op de documentatie user interface. Vandaar dat ik em even terug sleep naar Make ready.

michielverhoef commented 6 years ago

Goed punt, ik heb eea. anders geformuleerd. Sluti dit beter aan?

ehotting commented 6 years ago

@joeribekker Graag review op DoD / AC / taken, kan dit naar Sprint 1 ?

joeribekker commented 6 years ago

Lijkt me prima.

RvdKlip commented 6 years ago

In dit Issue staat 2x een definition of done. Waar is te lezen welke DOD het uiteindelijk geworden is?

Waar is 'design Common Ground' te zien?

(Als het hier gaat over 'de functionele documentatie van Michiel'...) Het gezichtspunt voor de gebruiker kan wat sterker aangezet worden. Er zou een acceptatiecriterium bij kunnen met 'Niet Developers worden happy van de wijze van navigatie en presentatie'.

Suggestie: Een opzet ongeveer gelijk aan DSO is wellicht ook toegankelijk voor beide doelgroepen(https://pre.omgevingswet.overheid.nl/ontwikkelaarsportaal/content/home). Lelijk hierin m.i. is het PDF gedoe. Misschien dat iets dergelijks als in dit voorbeeld (https://docs.alfresco.com/5.2/references/dev-services-filefolder.html) dan beter werkt. Uiteraard kan van daaruit ook gelinkt worden naar 'core developers materiaal'.

TCIMEddy commented 6 years ago

@ehotting @joeribekker @sergei-maertens snijden opmerkingen Ruud hout? Zo ja zijn ze verwerkt? Is deze user stories vanuit development perspectief ready? schermafbeelding 2018-06-25 om 11 22 02

sergei-maertens commented 6 years ago

@TCIMEddy @RvdKlip niet-developers aspect toegevoegd aan de acceptatiecriteria. De gelinkte opzet lijkt mij prima, het PDF gebeuren is inderdaad niet zo handig dus als browsable tekst is fijner. Er zijn voldoende technologien om vanuit 1 bronbestand (in markdown waarschijnlijk) meerdere versies te genereren (HTML, PDF, ePUB), dus dat vind ik geen zo'n issue.

sergei-maertens commented 6 years ago

Via #214 is https://ref.tst.vng.cloud/ in de lucht. Deze documentatie wordt ook continuously deployed bij het mergen van een pull request naar master.