Fórum Root.cz

Hlavní témata => Vývoj => Téma založeno: tomas111 01. 07. 2020, 11:19:22

Název: Dokumentace k softwaru
Přispěvatel: 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/ )?
Název: Re:Dokumentace k softwaru
Přispěvatel: vcunat 01. 07. 2020, 17:41:35
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
Název: Re:Dokumentace k softwaru
Přispěvatel: Google CTCCTCGGCGGGCACGTAG 01. 07. 2020, 18:35:18
dokumentace Kotlinu je web ve Flasku a kramdown

https://github.com/JetBrains/kotlin-web-site
Název: Re:Dokumentace k softwaru
Přispěvatel: luvar 01. 07. 2020, 20:23:17
Par klucovych slov do zoznamu:
Název: Re:Dokumentace k softwaru
Přispěvatel: vcunat 01. 07. 2020, 20:57:15
*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.
Název: Re:Dokumentace k softwaru
Přispěvatel: Ondrej_Malek 08. 07. 2020, 15:53:15
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 ?
Název: Re:Dokumentace k softwaru
Přispěvatel: ivoszz 08. 07. 2020, 18:03:05
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ě.
Název: Re:Dokumentace k softwaru
Přispěvatel: vcunat 11. 07. 2020, 19:55:14
pandoc (https://pandoc.org/) umí konvertovat leccos, včetně man, ale nejsem si jistý jestli takový přístup bude zde dobrý.
Název: Re:Dokumentace k softwaru
Přispěvatel: Zdeno Sekerák 12. 07. 2020, 22:55:46
tuhle otazku vyzkousej na devel.cz
Název: Re:Dokumentace k softwaru
Přispěvatel: Vrozkrokkop Kopalsson 13. 07. 2020, 10:26:03
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."
:(