V čem píšete dokumentaci k produktu?

PCnity

  • *****
  • 686
    • Zobrazit profil
    • E-mail
V čem píšete dokumentaci k produktu?
« kdy: 24. 01. 2014, 13:15:41 »
Hello,

Dopracovali sme sa do stavu ze mame funkcny novy produkt (HW Appliance) a potrebujeme k nemu vytvorit dokumentaciu. Nase terajsie fungovanie s wiki ale nie je uspokojive.
Moze to byt aj komercny sw.

Nas najvacsi problem s wiki je, ze po case vznikne roztriesteny system kde sa na niekolko pageoch opisuje to iste s roznou detainostou a aktualnostou.
Na interne pouzitie je to dostacujuce, pre klientov ale neakceptovatelne.

Ide o verejnu dokumentaciu funkci, navody na pouzitie, funkcia hladania je velmi vitana.
Dakujem.
« Poslední změna: 24. 01. 2014, 14:33:42 od Petr Krčmář »


Re:V čem píšete dokumentaci k produktu?
« Odpověď #1 kdy: 24. 01. 2014, 14:47:45 »
nemyslim, ze jakykoliv SW dokaze ukocirovat lidi, aby se to neroztristilo.
Děkuji za možnost editace příspěvku.

Plamen

Re:V čem píšete dokumentaci k produktu?
« Odpověď #2 kdy: 24. 01. 2014, 15:07:34 »
http://www.xmlmind.com/xmleditor/
Pravda, komerční, ale velmi pohodlný editor pro tvorbu dokumentace. Formát dokumentace je v mém případě Docbook XML, finální výstup dělám v PDF.

PCnity

  • *****
  • 686
    • Zobrazit profil
    • E-mail
Re:V čem píšete dokumentaci k produktu?
« Odpověď #3 kdy: 24. 01. 2014, 15:19:13 »
Dakujem za odporucanie DocBooku, tohoto riesenia sme sa trosku bali, nakolko aj marketing nam pise cast manualov.

Interne sme sa zamyslali nad tym ci existuje nejaky system, idealne web based, kde by som vedel napriklad rozpisat podrobne casti k jednotlivym modulom a ono by mi to potom kvazi skompilovalo hotovu dokumentaciu do pdf a html. Nieco ako wiki kde si mozem pozriet samostatne kazdy topic + funkcia poskladania do velkeho manualu vo formate pdf.

Ako zvladate updaty? Ako zvladate samostatne formaty? Ako exportovat dokuemntaciu do printoveho formatu?

42

  • **
  • 63
  • 42
    • Zobrazit profil
    • 42
Re:V čem píšete dokumentaci k produktu?
« Odpověď #4 kdy: 24. 01. 2014, 15:33:08 »
Ahoj,

záleží také na tom, zda jde o technickou dokumentaci nebo uživatelskou a dle toho zvolit šablony/software pro její generování. U technické dokumentace také v čem je to psaný.
Já sám osobně píšu technickou dokumentaci do firemního Redmine (možnost export do PDF atp.), ale existuje plno automatickýho generování (pro PHP: phpDoc, APIGen, ...).

Pro uživatelskou dokumentaci je úplně jedno kde to bude. Online je to fajn třeba v Confluence od Atlassianu. I ten Redmine je v pohodě.
42


PCnity

  • *****
  • 686
    • Zobrazit profil
    • E-mail
Re:V čem píšete dokumentaci k produktu?
« Odpověď #5 kdy: 24. 01. 2014, 15:39:22 »
Ide o uzivatelsku dokementaciu.

Produkt je hardwarovy, sklada sa z vela komponentov v roznych jazykoch... To sa vsak netyka adminov pre ktorych su manualy urcene. V podstate musime mat aj manual v printovej forme pre quick setup aj pdfko s popisom funkcii aj rozne use case ukazkove white papers.
Doteraz sme neboli v situacii ze by sa niekto z nas musel zaoberat tak podrobnou dokuemntaciou, cize sme dost clueless.

Nevedel som ze v RedMine sa da drzat dokuemntacia, na to sa tiez pozrieme. Dik,.

Masarka


eko

Re:V čem píšete dokumentaci k produktu?
« Odpověď #7 kdy: 27. 01. 2014, 17:22:10 »
git, dita-ot, oplugovany vim

PCnity

  • *****
  • 686
    • Zobrazit profil
    • E-mail
Re:V čem píšete dokumentaci k produktu?
« Odpověď #8 kdy: 27. 01. 2014, 17:57:45 »
Dakujem za vsetky odpovede.

Zo vsetkeho najlepsie nam zatial vychadza Confluence. Hrame sa s tym zatial len jeden den, a uz teraz sme si ten tool zamilovali. Export space do PDF, draft -> rc -> publish... WYSIWYG editor funguje spolahlivo.
A zatial nam staci 10 userov, cize cena nie je issue.

Re:V čem píšete dokumentaci k produktu?
« Odpověď #9 kdy: 27. 01. 2014, 18:30:10 »
a az si to propojis s jira, stash atd tak budes v sedmem nebi.
Děkuji za možnost editace příspěvku.

eMko

  • ****
  • 456
    • Zobrazit profil
    • E-mail
Re:V čem píšete dokumentaci k produktu?
« Odpověď #10 kdy: 27. 01. 2014, 22:15:51 »
po case vznikne roztriesteny system kde sa na niekolko pageoch opisuje to iste s roznou detainostou a aktualnostou.

Tomu nezabrání žádný soft. Zabránit tomu dokáže člověk - dokumentarista. Jedná se o _roli_ v sw procesu, nemusí to být pracovní pozice - prostě člověk, který je schopný napsat slušnou dokumentaci a udržet v dokumentech pořádek, klidně na part-time (ve zbytku může dělat cokoliv jiného, třeba testování nebo programování).

TV

Re:V čem píšete dokumentaci k produktu?
« Odpověď #11 kdy: 27. 01. 2014, 23:34:20 »
Zo vsetkeho najlepsie nam zatial vychadza Confluence. Hrame sa s tym zatial len jeden den, a uz teraz sme si ten tool zamilovali. Export space do PDF, draft -> rc -> publish... WYSIWYG editor funguje spolahlivo.
A zatial nam staci 10 userov, cize cena nie je issue.

Sice taky používám Confluence, ale zrovna na integrovaný PDF export bych úplně nesázel. Není to nosná funkce, takže omezená konfigurovatelnost, chybějící možnost rozumně nastavit šířky sloupců tabulek např. apod. Jinak shodou okolností zrovna testuju doplňky Ad Hoc Workflows a Content Publishing Plugin pro draft -> ... -> publish procesy jak zmiňuješ. Je to takové kostrbaté, dokumentace nedostatečně obsáhlá, ale asi to nějak půjde.

snajpa

Re:V čem píšete dokumentaci k produktu?
« Odpověď #12 kdy: 28. 01. 2014, 11:10:42 »
DocBook :)

m

Re:V čem píšete dokumentaci k produktu?
« Odpověď #13 kdy: 28. 01. 2014, 11:21:16 »
Confluence + Ad Hoc Workflows + Gliffy.. Bez toho by som asi neprezil :-)

Export do PDF a HTML je super. Export do Wordu je uz trosku horsi ale stale postacujuci. Ale ako pisali, export je len doplnkova fukcionalita.