Page 1 of 2 1 2 LastLast
Results 1 to 15 of 19

Thread: Help Documentie software

  1. #1

    Help Documentie software

    Hallo hallo,

    Momenteel gebruik ik de gratis versie van helpndoc voor het schrijven van de help voor mijn software. Op zich ben ik wel tevreden, maar ik vroeg me af of er andere tools zijn die de moeite waard zijn om te bekijken?

    Bij voorbaat dank!

  2. #2
    Fornicatorus Formicidae VideoRipper's Avatar
    Join Date
    Mar 2005
    Location
    Vicus Saltus Orientalem
    Posts
    5,708
    Ik kan je hier helaas niet bij helpen omdat ik zelf geen documentatie schrijf (daar heb ik collega's voor),
    maar moest daardoor wel ineens hieraan denken:
    Click image for larger version. 

Name:	flat,550x550,075,f.u1.jpg 
Views:	109 
Size:	51.2 KB 
ID:	7799
    TMemoryLeak.Create(Nil);

  3. #3
    Het gaat hier vanzelfsprekend over documentatie voor de eindgebruiker. De meeste daarvan kunnen waarschijnlijk geen code begrijpen

    Maar ik ben het met je eens. Ik ben het wel eens met de uitspraak dat de beste manier van je code documenteren de code zelf is. Recentelijk heb ik wat video's van Robert C. Martin bekeken over hoe je code schoon kunt houden. Bijzonder interessant en vol met praktische tips. Echt een aanrader!

  4. #4
    leuk tooltje Luigi, kende het nog niet.

    Ik ben al een poosje redelijk gecharmeerd van documentatie in markdown. Ik gebruik Markdownpad om het te schrijven. Omdat het tekstbestanden zijn en ik ze in gitlab in een git repo zet kan ik mijn documentatie heel makkelijk diffen. In de browser van gitlab kun je het gerendered lezen.

    Voor uitvoer gebruik ik pandoc. Als ik bv een pdf document moet maken dan render ik mijn markdown via pandoc naar een libreoffice odt. Het leuke is dat je een template mee kunt geven aan pandoc, zodat meteen stijlen van je huisstijl worden gebruikt. Via Libreoffice maak ik dan ook een pdf.

    Moet ik een simpele set documentatie op een webserver of usb stick leveren dan gebruik ik mdwiki. Mdwiki is een javascript clientside renderer. Dus 1 index.html (de de javascript bevat) een buts .md bestanden en een paar yaml bestanden voor de config en je bent klaar.

    Of pandoc ook chm kan genereren weet ik niet, html kan wel. Ook epub is mogelijk. Alles vanuit een en dezelfde markdown source (onder versiebeheer)

  5. #5
    mov rax,marcov; push rax marcov's Avatar
    Join Date
    Apr 2004
    Location
    Ehv, Nl
    Posts
    10,357
    Voor werk schrijf ik docs in Latex, en dan naar PDF. Ik heb geen in-applicatie help.

    pandoc lijkt ook latex als PDF engine te gebruiken.

    Redenen beetje als Benno, kwalitatief goede output, plain text input, dus in versie beheer te zetten, en vooral uitgebreide macro en include opties om gedeelde documentatie te parameterizeren.

    Standaard hoofdstukken delen was een van de hoofdredenen om van recht toe recht aan Word docs uit de begin tijd naar Latex te gaan.

    Er is enorm veel mogelijk met Latex, en verschrikkelijk makkelijk informatie over te vinden (ik heb hier een halve meter documentatie over mijn documentatiegeneratie systeem). Dus niet beperkt door een of andere vendor die een feature niet wil implementeren, of bug wil fixen. Je komt er altijd wel uit.

    En daarnaast is het een veilige keuze. Latex bestaat nog als niemand meer het huidige word formaat kan lezen.

    In sommige offertes zitten wetenschappelijke delen in ( wiskundige, natuurkundige en scheikundige formules en symbolen) en er is ook een source code package met een simpele highlighting voor een zwik talen, voor voorbeeldjes en pseudocode e.d.

    Windows heeft een diverse makkelijke latex distros tegenwoordig, en op Linux (server) is het helemaal makkelijk.

  6. #6
    mov rax,marcov; push rax marcov's Avatar
    Join Date
    Apr 2004
    Location
    Ehv, Nl
    Posts
    10,357
    Benno: CHM is gecompileerde html met wat indexen en wat files voor topic -> html file mappings. (nuttig als b.v. de namen van de html niet stabiel zijn agv generatie).

    Al is voor CHM gemaakte html wat mooier omdat "plain" html vaak navigatie controls heeft die bij CHM in de viewer zitten.

  7. #7
    Het is inderdaad een groot voordeel als je versiebeheer kunt gebruiken voor je docs. Met HelpNDoc kan dit zover ik weet niet. Er is wel een andere tool die dit wel kan, maar die kost ca 600$ en dat vind ik een beetje veel van het goede. Een ander nadeel van HelpNDoc is dat je maar één item te gelijk kunt openen.

    Ik ga alle genoemde opties een rustig bekijken! Bedankt voor de feedback!

  8. #8
    je zou ook eens in de open source sectie kunnen kijken. Marcel heeft daar ooit bdoc in gezet, die chm bestanden op kon leveren.

  9. #9
    mov rax,marcov; push rax marcov's Avatar
    Join Date
    Apr 2004
    Location
    Ehv, Nl
    Posts
    10,357
    FPC/Lazarus heeft ook wat CHM grut, en een documentatie pakket erover heen (fpdoc).

    fpdoc is meer source(SDK) documentatie, maar je kan ook gewoon topics er mee maken. Ik geloof dat bij Lazarus een "doceditor" hiervoor zit.

    In tegenstelling tot de meeste producten, produceert FPC echt CHMs, niet HHP projecten die je dan met de antieke MS compiler moet compileren.

    Een van de voordelen van een niveau boven latex gebruiken (zoals bdoc, fpdoc,pasdoc,pandoc,doxygen,sphinx, castle noem ze maar op) is dat de html generatie via Latex niet ideaal is.

    Dus html en vaak rtf worden direct gegenereerd, en PDF enz gaat via latex.
    Last edited by marcov; 12-Sep-18 at 20:59.

  10. #10
    Ik vind versiebeheer ook een goede manier om je code te documenteren. In een commit message kan je namelijk precies kwijt wat je ticket nummer was, wat je redenatie was om het zo op te lossen, linkjes naar documentatie, stackoverflow of NLDelphi posts waar je de oplossing hebt gevonden, enz.
    Je kan helemaal los gaan omdat het niet je code 'vervuilt', en het verdwijnt een beetje uit het zicht zodra iemand de code aanpast (de 'blame' tool wijst naar de laatste commit).

    Dus meestal liever daar dan in comments.

    Maar dat lost jouw probleem niet op.

    Ik schrijf, zoals Benno, ook best veel in Markdown, maar dat is vooral de technische documentatie (voor zover we die hebben). De gebruikersdocumentatie (voor zover we die hebben) staat meestal in Confluence. Dat is een van de zovele betaalde Wiki-oplossingen. Het voordeel is dat veel mensen het kunnen lezen en bewerken. Het nadeel is dat het handen vol met klauwen kost, en soms weleens een beetje traag is. Niettemin, een wiki-achtige opzet heeft ook voordelen omdat gebruiker het eventueel zelf kunnen aanpassen.

    Ik heb dat voor ons weleens overwogen, om gewoon te linken naar een wiki-pagina voor een bepaald schermpje, zodat de tech- of process-savvy mensen op een afdeling precies kunnen beschrijven hoe dat schermpje in hun workflow past.

    Nog even teruggrijpend op Benno's Pandoc, het lijkt erop dat het geen CHM ondersteunt, maar inderdaad wel ePub, en onderaan deze discussie wordt een Calibre geopperd, een freeware tooltje dat o.a. ePub naar CHM kan converteren.
    1+1=b

  11. #11
    mov rax,marcov; push rax marcov's Avatar
    Join Date
    Apr 2004
    Location
    Ehv, Nl
    Posts
    10,357
    Een deel van een epub lezer heb ik ook nog wel in lazarus. Dus als je je even kwaad maakt kan je je eigen customized tooltje in elkaar sleutelen, b.v. met wat dom rearrangements ertussen.

  12. #12
    en onderaan deze discussie wordt een Calibre geopperd, een freeware tooltje dat o.a. ePub naar CHM kan converteren.
    Die had ik nog niet gezien.

    Mijn ervaring is wel dat pandoc en calibre nog niet echt samen op date zijn geweest . Ik ben met name aan het kijken geweest naar een geautomatiseerde workflow om markdown te publiceren in een calibre project, aangezien calibre een echt opmaakpakket is. Maar het blijft behelpen met een opstapeling van trucjes, dus ik heb de moed opgegeven. Voor mijzelf was de route via libreoffice met een aangepast sjabloon voldoende.

    Over het algemeen wordt de html output van pandoc geprezen, je kunt ook je eigen css gebruiken zou je dat willen. Dan heb je volgens mij alleen nog zo'n index bestand nodig en de ms chm compiler.

    Confluence is inderdaad ook een hele bekende, helaas weer met zijn eigen opmaaktaaltje. Zelf gebruik ik voor intern gebruik ook gebruik van de wiki functionaliteit in gitlab. De wiki in gitlab is zelf ook een (interne) git repository. Het leuke is dat je die dus gewoon lokaal kunt halen als git repo en ook offline kunt bewerken. Gitlab stelt ook wat extra tooling beschikbaar zodat je die wiki online kunt publiceren, los van je gitlab (waar je geen vreemden wilt zien ). Github heeft volgens mij ook zoiets.

  13. #13
    mov rax,marcov; push rax marcov's Avatar
    Join Date
    Apr 2004
    Location
    Ehv, Nl
    Posts
    10,357
    Zoals gezegd moet de html generator dan wel een optie hebben om geen navigatie controls te gegeneren, en in plaats daarvan een TOC + index.

    De TOC (.hhc) is iets wat als een tree(-view) structuur dient met elke node een reference naar een html (of html#anchor) zeg maar. Index (.hhk file) is meer een alfabetische index. Deze zijn ook zichtbaar als tabs in de CHM viewer.

    Het ziet er dan wat amateuristisch uit als dan op alle html pagina's nog "<-prev up next->" enz zit.
    Last edited by marcov; 13-Sep-18 at 20:49.

  14. #14
    Wellicht kun je iets met Help and Manual of Doc-O-Matic?
    Onmogelijk... Is geen feit, maar een mening.

  15. #15
    Help and Manual had ik al gezien, maar die is vrij prijzig. Ik wist niet dat Doc-O-Matic ook een help tools had voor eindgebruikers. Ik dacht altijd dat dit alleen voor code documentatie was. De prijs is heel redelijk. Ik ga even een demo downloaden.

Page 1 of 2 1 2 LastLast

Thread Information

Users Browsing this Thread

There are currently 1 users browsing this thread. (0 members and 1 guests)

Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •