Closed ehotting closed 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?
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 [?]
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.
Goed punt, ik heb eea. anders geformuleerd. Sluti dit beter aan?
@joeribekker Graag review op DoD / AC / taken, kan dit naar Sprint 1 ?
Lijkt me prima.
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'.
@ehotting @joeribekker @sergei-maertens snijden opmerkingen Ruud hout? Zo ja zijn ze verwerkt? Is deze user stories vanuit development perspectief ready?
@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.
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.
.... zodat ik snel alle informatie heb die ik nodig heb.
Definition of done
Acceptatiecriteria
Taken