Software pro tvorbu dokumentace

[opiio]

Potrebujeme zdokumentovat system, vice pro implemetatory nez uzivatele nebo programatory. V dokumentaci by se mela ke kazde entite v systemu (modul, element, zapojeni, funkcnost) evidovat nastaveni, ukazky, obrazky, linky, checklist a spravovat jejich provazani na ostatni entity. Libil by se mi system podobny mind mapam.

- entity usporadane ve stromove strukture
- provazani entit mimo stromovou strukturu s definici vztahu (modul ma element, zapojeni elementu apod.)
- moznost pridat k entite popisy, obrazky, odkazy
- fulltextove hledani

Nechci pouzivat cokoli, kde se vytvari stranky/text (wiki apod.). Informace by mely byt heslovite (seznam bodu) zadny romany. Mind mapa by byla fajn, ze by se dalo rychle proklikat k mistu, ktere se resi. K zapojeni teto funkcnosti potrebuji to to to, souvisi s timto modulem, vzorove nastaveni vypada takhle, v administraci tady, checklist pro kontrolu zapojeni je takovy.

Dotazy na timto stromem, aby mi vratil napr. checklist pro definovane module/elementy/zapojeni by bylo skvely.

Resili jste neco podobneho? diky

[Reklama]

[Mirek Prýmek]

Nechci pouzivat cokoli, kde se vytvari stranky/text (wiki apod.). Informace by mely byt heslovite (seznam bodu) zadny romany.

Wiki nemusí obsahovat dlouhý text. Wiki+markdown mi přijde jako přesně to, co hledáš. Pokud těch informací nebude zas tak moc, klidně i jenom prolinkované markdown soubory + nějaký jednoduchý renderer.

U mindmap budeš mít spíš limitovaný možnosti formátování a bude kostrbaté nebo nemožné dělat prokliky. Já bych tou cestou nešel.

Osobně používám na dokumentaci wiki. Romány píšu jenom tam, kde to je účelné. Kde stačí heslovitě, píšu heslovitě. Mám to na MoinMoin. Nejsem z něho nijak odvázanej, ale taky nemám žádný silný důvod to měnit.

[Mirek Prýmek]

Ještě k tomuhle:

- entity usporadane ve stromove strukture

Já mám taky stromy rád, ale skoro vždycky ta původní představa "uspořádám to podle tohodle kritéria tak a tak" nakonec narazí na nějakou situaci, kdy je to nešikovné a hodí se mít i nějakou alternativu, která umožňuje v případě potřeby udělat i bohatší strukturu - kromě stromu jsou nakonec stejně potřeba i nějaké "symlinky", hyperlinky, tagy...

[Ondra Satai Nekola]

Ještě k tomuhle:

- entity usporadane ve stromove strukture

Já mám taky stromy rád, ale skoro vždycky ta původní představa "uspořádám to podle tohodle kritéria tak a tak" nakonec narazí na nějakou situaci, kdy je to nešikovné a hodí se mít i nějakou alternativu, která umožňuje v případě potřeby udělat i bohatší strukturu - kromě stromu jsou nakonec stejně potřeba i nějaké "symlinky", hyperlinky, tagy...

Presne tak.
V lepsim pripade si to uvedomi jeste tvurce dokumentace.
V horsim az podeji ctenar zjisti, ze jeho mentalni model je uplne jiny, nez mentalni model tvurce.

[Mirek Prýmek]

V horsim az podeji ctenar zjisti, ze jeho mentalni model je uplne jiny, nez mentalni model tvurce.

Jo, to je vzdycky strasny. A vubec nejhorsi je, pokud ten autoruv model vychazi z nejake interni struktury (kodu, site, systemu...), kterou ctenar nezna a ani znat nemuze/nesmi. Autor pak ma pocit, ze napsal naprosto skvelou, logickou dokumentaci a ctenar by si pri cteni nejradsi vypichl oci tuzkama.

[Reklama]

[opiio]

Ještě k tomuhle:

- entity usporadane ve stromove strukture

Já mám taky stromy rád, ale skoro vždycky ta původní představa "uspořádám to podle tohodle kritéria tak a tak" nakonec narazí na nějakou situaci, kdy je to nešikovné a hodí se mít i nějakou alternativu, která umožňuje v případě potřeby udělat i bohatší strukturu - kromě stromu jsou nakonec stejně potřeba i nějaké "symlinky", hyperlinky, tagy...

Ano, zkousel jsem cast sestavit a nedava to smysl. Bude lepsi mit samostatne entity a vztahy mezi nimi. Tedy strukturou by se pohybovalo na zaklade tech vztahu (ma element, patri modulu, ma funkcnost apod.).

Ohledne citelnosti.. v nasem pripade by to odpovidalo strukture systemu (v podstate i kodu), ale je to pro implementatory, ty strukturu znaji a nebo se ji musi naucit. Pro koncoveho uzivatele bych na to sel jinak.

[opiio]

Nechci pouzivat cokoli, kde se vytvari stranky/text (wiki apod.). Informace by mely byt heslovite (seznam bodu) zadny romany.

Wiki nemusí obsahovat dlouhý text. Wiki+markdown mi přijde jako přesně to, co hledáš. Pokud těch informací nebude zas tak moc, klidně i jenom prolinkované markdown soubory + nějaký jednoduchý renderer.

U mindmap budeš mít spíš limitovaný možnosti formátování a bude kostrbaté nebo nemožné dělat prokliky. Já bych tou cestou nešel.

Osobně používám na dokumentaci wiki. Romány píšu jenom tam, kde to je účelné. Kde stačí heslovitě, píšu heslovitě. Mám to na MoinMoin. Nejsem z něho nijak odvázanej, ale taky nemám žádný silný důvod to měnit.

Wiki jsme zkouseli a moc se nam to nepovedlo. Problem je asi podobny jako u stromu, clovek to musi chytit z nejakeho konce. Tak se vytvareji texty na nejakou cast systemu. Neco konkretniho se musi hledat v nejake te obsahlejsi casti. Problemova byla i aktualizace, pokud se neco zmenilo, bylo to zminene na vice mistech ve wiki.

Ten "mind map" by mel jeste jednu vyhodu. Slo by vygenerovat postup na nejakou cinnost napr. checklist pro prevod na produkcni prostredi (podle zapojenych entit v systemu), seznam podkladu pro zprovozneni apod.

[darebacik]

Tiez si myslim, ze dokuwiki by mohla byt OK, ale uz pri navrhu je potreba si poriadne premysliet ako bude navrhnuta. Ak by sa vsak jednalo o rozsiahly projekt je mozne ze aj autor bude mat po case problem nieco do wiki implementovat.
Sam pouzivam wiki na dokumentovanie (ale je to len take moje domace) a celkom sa to da.
Je to strom, obrazky v pohode a mnozstvo zaujmavych pluginov.
Co sa tyka zmien na viacerych miestach. Snazim sa robit tak, ze co uz je zdokumentovane, nedokumentujem znova ale pouzijem interny link.
A aj ked by si potreboval nieco obkecavat (myslim tym roman na 2 strany) tak pouzijes spoiler

[Ladislav Zitka]

Ja se snazim delat dokumentaci primo soucasti kodu a generovat, nejde jen o neco jako API doc, ale i o modely datovych objektu, architektury (AsciDoc, MultiMarkDown, apod., a vygenerovat to ven do nejakeho web systemu pro nahlizeni(Confluence, Nuxeo) pomoci CI pipelines on the fly pres web services tech systemu. Proste jakmile neni dokumentace soucasti zdrojovejch kodu, tak vetsinou vidim, ze se to rozchazi (nerikam, ze v tom nemam prsty nekdy).

[gill]

Ja se snazim delat dokumentaci primo soucasti kodu a generovat, nejde jen o neco jako API doc, ale i o modely datovych objektu, architektury (AsciDoc, MultiMarkDown, apod., a vygenerovat to ven do nejakeho web systemu pro nahlizeni(Confluence, Nuxeo) pomoci CI pipelines on the fly pres web services tech systemu. Proste jakmile neni dokumentace soucasti zdrojovejch kodu, tak vetsinou vidim, ze se to rozchazi (nerikam, ze v tom nemam prsty nekdy).

i documentace v komentarich v kodu se muze rozchazet. Nejlepe je psat dokumentaci ve forme doctestu.