reklama

Software pro tvorbu dokumentace

Software pro tvorbu dokumentace
« kdy: 12. 04. 2019, 12:07:57 »
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


Re:Software pro tvorbu dokumentace
« Odpověď #1 kdy: 12. 04. 2019, 13:56:47 »
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.

Re:Software pro tvorbu dokumentace
« Odpověď #2 kdy: 12. 04. 2019, 14:01:08 »
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...

Re:Software pro tvorbu dokumentace
« Odpověď #3 kdy: 12. 04. 2019, 14:37:59 »
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.

Re:Software pro tvorbu dokumentace
« Odpověď #4 kdy: 12. 04. 2019, 14:51:02 »
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.


Re:Software pro tvorbu dokumentace
« Odpověď #5 kdy: 12. 04. 2019, 16:21:22 »
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.

Re:Software pro tvorbu dokumentace
« Odpověď #6 kdy: 12. 04. 2019, 16:40:19 »
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.

Re:Software pro tvorbu dokumentace
« Odpověď #7 kdy: 15. 04. 2019, 12:53:15 »
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

 

reklama