Fórum Root.cz
Hlavní témata => Vývoj => Téma založeno: tomas111 01. 07. 2020, 11:19:22
-
Dobrý den,
chci se zeptat zkušených jakým způsobem řešíte/se řeší dokumentace softwaru. Jde mi hlavně o nástroje co se pro to využívají. A v čem se například píší dokumentace k programovacím jazykům (například https://kotlinlang.org/docs/reference/ )?
-
Sphinx mi nepřijde špatné, mám celkem pozitivní dlouhodobé zkušenosti: https://www.sphinx-doc.org Některým projektům, zvláště menším F/LOSS se s tím může hodit i hosting zdarma: https://readthedocs.org
-
dokumentace Kotlinu je web ve Flasku a kramdown
https://github.com/JetBrains/kotlin-web-site
-
Par klucovych slov do zoznamu:
- doxygen - volakedy pri .NET projektoch som videl...
- asciidoctor - tusim vychadza z docbook-u a je user friendly za mna. Aj komunita, aj jazyk
- restdocs - pre springove rest projekty fajn vec. Spaja jednak testovanie a jednak dokumentovanie. Kazdy test sa da pouzit ako ukazka v dokumentacii a nestoji to moc namahy
- LaTeX - na vsetko, co ma mat pekny vystup :)
- javadoc
- scaladoc
-
*TeX bych škrtl jako nedůležitý (pro tento případ). Jsou pouze na stránkovaný výstup (PDF, papír) a myslím že tak většina lidí SW dokumentaci nechce číst. Aby bylo jasno, pro PDF a papír je považuji za velmi dobrý (mezi-)formát.
-
Přifařim se.
Nevíte někdo jestli je nějaký "standartní-casto pouzivany" dokumentovatko ktere by umelo generovat jak nejakou web/pdf dokumentaci tak i man pages ?
-
Přifařim se.
Nevíte někdo jestli je nějaký "standartní-casto pouzivany" dokumentovatko ktere by umelo generovat jak nejakou web/pdf dokumentaci tak i man pages ?
Nevím, jestli je to standard, ale asciidoc je docela dobrý format a asciidoctor z něj umí generovat PDF/HTML i MAN stránky. Ale man stránky jsou dost specifické, takže je asi stejně potřeba psát samostatně.
-
pandoc (https://pandoc.org/) umí konvertovat leccos, včetně man, ale nejsem si jistý jestli takový přístup bude zde dobrý.
-
tuhle otazku vyzkousej na devel.cz
-
IMHO není tak důležité jestli dokumentace je vytvořena barevně na nejnovějším superpočítači nebo napsaná křídou na tabuli a ofocená. Hlavní je vůle tu dokumentaci poskytnout.
Třeba mně se kdysi stalo, že jsem byl na jednání s firmou co pro firmu, kde jsem byl tehdy zaměstnaný vyvíjela elektroniku (velkou asi tak do větší dlaně). Chtěl jsem, aby součástí dokumentace bylo i něco jako vývojový diagram FW (zdroják ne, stejně bychom tomu p. r. d. rozuměli), například abychom mohli odhadnout, když se za téhle situace stane tohle, kde asi je příčina. Odpověděli: "To není naší zvyklostí." Já jsem, Bohu žel, nebyl v pozici, abych mohl odpovědět: "Pokud máte zájem o další spolupráci s námi, tak od teďka to vaší zvyklostí je. A hned to dáme do zápisu."
:(