/u/204872/crop65a1d5f52b87f.png?f=community)
Ik zoek een stukje software waarin ik wat titels, functies, stukjes voorbeeldcode, eventueel een afbeelding en een grapje kan maken, zonder ook maar één fornicate om de layout te hoeven geven.
Vervolgens druk ik op een knopje en *bam* vet mooi netjes handig indexed, color-coded pdf en/of html handleiding.
Met de tweaker search engine kom ik veelal advies tegen om LaTeX te gaan gebruiken, een extreem krachtig stukje software markup met een enorme leercurve die daardoor haast garandeert dat collega's het project niet over zullen nemen.
Er zijn veel grote projecten (e.g. jQuery, Wordpress, etc) die erg dynamisch zijn, en ik kan me niet voorstellen dat een team constant alle nieuwe functies en parameters update in de tabelletjes van de documentatie.
Gelukkig is er zoiets als JSDoc, wat ondanks de naam doet vermoeden ook voor andere talen geschikt is (en wordt gebruikt door o.a. Wordpress), maar met welke software kan je dit indexeren en omzetten naar documentatie? Bemerk daarbij dat goede documentatie ook voorbeeldcode en tekstuele uitleg bevat, die je in JSDoc niet terugziet. Ik denk dat er een soort hybriede moet zijn tussen JSDoc achtige auto-generate/update documentatie en manually added content.
Een mooi voorbeeld - maar niet geheel wat ik bedoel - van een resultaat van het eerste (JSDoc auto-generate) is ADWiki. Het parsed de JSDoc en zet dit realtime om naar dynamische documentatie: Voorbeelddocumentatie.
Maar dit is niet wat ik wil om twee redenen:
1) Het is dynamisch, moet op de server draaien en bekijkt realtime de source-code. Ik wil statische documentatie kunnen genereren.
2) Het haalt ALLES uit de JSDoc source-code waardoor je meer comments dan code hebt en je niet meer lekker kan coden. Dit doen jQuery, Wordpress, ExtJS en allerlei Open Source projecten met mooie documentatie ook niet zo.
Verder heb ik nog een aantal projectjes gevonden die al 4 jaar geleden doodgegaan zijn. Maar dit moet bestaan. Er is vast iets relatiefs bekends waar ik gewoon steeds langsheen ben gegoogled, maar er is hier vast iemand die al lang en breed doet wat ik zoek, en mij hierin kan adviseren.
Idealiter zoek ik een soort hybride wat JSDoc parst en een apart document met wat verhaaltjes en uitleg, maar ik ben nu ook maar aan het fantaseren. Misschien is er nog iets veel handigers.
Vervolgens druk ik op een knopje en *bam* vet mooi netjes handig indexed, color-coded pdf en/of html handleiding.
Met de tweaker search engine kom ik veelal advies tegen om LaTeX te gaan gebruiken, een extreem krachtig stukje software markup met een enorme leercurve die daardoor haast garandeert dat collega's het project niet over zullen nemen.
Er zijn veel grote projecten (e.g. jQuery, Wordpress, etc) die erg dynamisch zijn, en ik kan me niet voorstellen dat een team constant alle nieuwe functies en parameters update in de tabelletjes van de documentatie.
Gelukkig is er zoiets als JSDoc, wat ondanks de naam doet vermoeden ook voor andere talen geschikt is (en wordt gebruikt door o.a. Wordpress), maar met welke software kan je dit indexeren en omzetten naar documentatie? Bemerk daarbij dat goede documentatie ook voorbeeldcode en tekstuele uitleg bevat, die je in JSDoc niet terugziet. Ik denk dat er een soort hybriede moet zijn tussen JSDoc achtige auto-generate/update documentatie en manually added content.
Een mooi voorbeeld - maar niet geheel wat ik bedoel - van een resultaat van het eerste (JSDoc auto-generate) is ADWiki. Het parsed de JSDoc en zet dit realtime om naar dynamische documentatie: Voorbeelddocumentatie.
Maar dit is niet wat ik wil om twee redenen:
1) Het is dynamisch, moet op de server draaien en bekijkt realtime de source-code. Ik wil statische documentatie kunnen genereren.
2) Het haalt ALLES uit de JSDoc source-code waardoor je meer comments dan code hebt en je niet meer lekker kan coden. Dit doen jQuery, Wordpress, ExtJS en allerlei Open Source projecten met mooie documentatie ook niet zo.
Verder heb ik nog een aantal projectjes gevonden die al 4 jaar geleden doodgegaan zijn. Maar dit moet bestaan. Er is vast iets relatiefs bekends waar ik gewoon steeds langsheen ben gegoogled, maar er is hier vast iemand die al lang en breed doet wat ik zoek, en mij hierin kan adviseren.
Idealiter zoek ik een soort hybride wat JSDoc parst en een apart document met wat verhaaltjes en uitleg, maar ik ben nu ook maar aan het fantaseren. Misschien is er nog iets veel handigers.
[ Voor 5% gewijzigd door Sando op 16-03-2013 23:28 ]
🇪🇺 Buy from EU (GoT)