A túl sok ábra, diagram az minden dokumentációban szívás, és nehéz megoldani plain text alapon, még az SVG van hozzá a legközelebb, de már az se annyira olvasható folyószövegben, megtöri a szabad írást.
A kolléga ráadásul programozós dokumentációban keresi, ahhoz túl sok ábra nem szokott tartozni. Az, hogy pont nem ismerek egy általad ajánlott megoldást, az nem von le a véleményem szakmai értékéből. Nyilván nem ismerhetek mindent, annyiféle megoldás van. Eleve nem is vitattam, hogy alkalmas lehet a feladatra, meg nem én keresek toolokat, hanem a topikindító, így nem tartom kötelességemnek, hogy mindent kipróbáljak és ismerjek. Nekem, ha ilyen technikai doksit kell csinálni, megvan rá az eszköztáram, HTML5, pandoc markdown to HTML5, XeTeX to pdf.
A standard markdown-ban meg kb. semmi sincs. Tud egy-két alap formázást, vastaggal, dőlttel szedés, függőleges vonal, néhány heading szint, verbatim code, link-kép, kézi lista, és kifújt. Semmifelé szövegigazítós csicsa (pl. sorkizárás, középre zárás, ezek CSS-ben pótolhatók később), semmi dinamikus tartalom, semmi változó, semmi automatikus számozás, mivel nem erre lett kitalálva. Akinek erre van igénye, az komolyabb nyelven írja. De ezek a hiányosságok megoldhatók kézzel, meg tartalomszervezéssel is, pl. crossreference-t nem sorszám alapján hivatkozol, hanem linkként, meg címkékkel, amit viszont a markdown tud. Néhány markdown dialektus, mint a pandoc, meg a gitlab/github, tudnak extrákat, de azok sem arra valók, hogy LaTeX szintű formázásokat meg mindenféle automatizált jegyzéket meg mindent hozzál létre. Vagyis azt is tudják, de ahhoz markdownon kívüli kódrészeket is be kell ágyazni a dokumentumba, a pandoc markdownban változókat is kezel, akármilyen nyelven, amihez fent van interpreter, csak ha ilyeneket kezd el valaki a markdown doksijába ágyazni, akkor szerintem a markdown értelme, egyszerűsége veszik oda, és nem volt értelme nekiállni ebben a formátumban. Kicsit olyan ez, mintha valaki magas szintű nyelven írt kódban elkezd túl sok ASM betétet beszúrni.