V čem píšete dokumentaci / manuál? rubrika: Administrace: Software

8 tdvorak
položil/-a 1.10.2014

Rád bych se zeptal, v čem píšete dokumentaci a jak ji spravujete. Převzal jsem sw produkt / aplikaci, ke kterému se dosud dokumentace psala řadu let ve wordu a přežívala hlavně v e-mailech a na sdílených discích.

Dokumentace je v podstatě firemní word šablona a 50 stran textu a screenshotů.

Rád bych takovou věc verzoval a vůbec pojal tak nějak od základu pořádně. Když začnu word dokument verzovat v GITu, moc mi to nepomůže. Takže mě napadlo překlopit dokumentaci do lepšího formátu (markdown?) a začít ji verzovat tak. Nadále ale musím odevzdávat word dokument, je tedy nutné mít možnost mezi formáty dokumentaci konvertovat. Kdyby šlo ze zdrojových souborů vygenerovat i html verzi, bylo by to super.

Hlavní problémy, které chci vyřešit

  • Jedno primární uložiště
  • Jasná historie změn (aby bylo možné sledovat změnu na úrovni řádku, ne celého dokumentu)
  • Snadná spolupráce na aktualizaci dokumentace
  • Možnost exportu do PDF/DOC

Používáte pro podobné situaci nějaký nástroj nebo postup?

Díky za každý tip.

Komentáře

  • Anonym : u mě vede Google Docs + git + Google Code Prettify Add-on; sice to není nejlepší z pohledu správy kódu, ale přehlednost dokumentu, komentáře, spolupráce, verzování = TOP! — 5.4.2015
  • Tomáš Tintěra : Používáme teď cvičně Google spreadsheets jako výkaz hotových úkolů. A verzování má své slabiny. U dané buňky nemohu zjistit kdo a kdy ji modifikoval (v SVN blame). Také si nemohu vypsat změny od určitého autora. Pro týmovou tvorbu dokumentace považuji verzování google docs za nedostatečné. To už mohu verzuji lépe s Office + Tortoise SVN. (A možná by stačilo možná i CVS). Na druhout stranu online spolupráce víe autorů je naopak u Google docs nejlepší co znám. U jednodušších případů, kam náše cvičení spadá, nevznikne potřeba řešit merge. — 5.4.2015
odkaz Vyřešeno
8 tdvorak
odpověděl/-a 30.3.2015

Nakonec to vypadá, že nejvhodnější varianta je pro mě GitBook.

Zdrojový text píšu v Markdown. GitBook poskytuje offline dvoupanelový editor, který ihned zobrazuje vyrenderovanou verzi. Následně pak vygeneruje ze zdrojů HTML stránky a PDF manuál (včetně rejstříku, cover obrázku a pod). Když chci, můžu editovat ve svém oblíbeném textovém editoru.

Soubory verzuji zároveň s aplikací v git/SVN repository a spolu s novou feature můžu ihned commitovat i upravenou dokumentaci.

Jejich online platformu ani online editor nepotřebuji a není nutné dokumentaci nijak vázat s účtem na gitbook.com. Když se později rozhodnu v budoucnu změnit nástroj z GitBook na jiný, nic mi neváže data. Jsou to jen prosté .md soubory a jednoduchý rejstřík se strukturou:

* [Introduction](README.md)
* [Documentation usage](introduction/README.md)
* [Overview](overview/README.md)
   * [Functional Overview](overview/functional_overview.md)
   * [Architecture and Interfaces](overview/architecture_and_interfaces.md)

Taková data by neměl být problém přemigrovat jinam (téměř bezpracně třeba jako statický Jekyll web).

Díky všem za tipy a komentáře!

Pro zobrazení všech 9 odpovědí se prosím přihlaste:

Rychlé přihlášení přes sociální sítě:

Nebo se přihlaste jménem a heslem:

Zadejte prosím svou e-mailovou adresu.
Zadejte své heslo.

Aktuální otázky v rubrice Administrace: Software

Otázky uživatele tdvorak