Dokumentace k softwaru

Dokumentace k softwaru
« kdy: 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/ )?


vcunat

  • ***
  • 121
    • Zobrazit profil
    • E-mail
Re:Dokumentace k softwaru
« Odpověď #1 kdy: 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

Re:Dokumentace k softwaru
« Odpověď #2 kdy: 01. 07. 2020, 18:35:18 »
dokumentace Kotlinu je web ve Flasku a kramdown

https://github.com/JetBrains/kotlin-web-site

luvar

  • ***
  • 225
    • Zobrazit profil
    • E-mail
Re:Dokumentace k softwaru
« Odpověď #3 kdy: 01. 07. 2020, 20:23:17 »
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

vcunat

  • ***
  • 121
    • Zobrazit profil
    • E-mail
Re:Dokumentace k softwaru
« Odpověď #4 kdy: 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.


Re:Dokumentace k softwaru
« Odpověď #5 kdy: 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 ?

Re:Dokumentace k softwaru
« Odpověď #6 kdy: 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ě.

vcunat

  • ***
  • 121
    • Zobrazit profil
    • E-mail
Re:Dokumentace k softwaru
« Odpověď #7 kdy: 11. 07. 2020, 19:55:14 »
pandoc umí konvertovat leccos, včetně man, ale nejsem si jistý jestli takový přístup bude zde dobrý.

Re:Dokumentace k softwaru
« Odpověď #8 kdy: 12. 07. 2020, 22:55:46 »
tuhle otazku vyzkousej na devel.cz

Re:Dokumentace k softwaru
« Odpověď #9 kdy: 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."
:(