V čem psát dokumentaci?



Zdravím, chtěl bych se zeptat v čem dnes (roku 2020) psát dokumentaci k vyvíjenému softwaru. Psát by to mělo více lidí a pokuď bude program zdarma tím lépe. Možná než psát co přesně potřebuji aby program uměl, tak mě zajímají vaše požadavky a doporučený software.
Tak ono zalezi o jakou dokumentaci ti jde. Muzes mit dokumentaci ve forme JavaDoc pro Javovske aplikace. K tomu ti staci vyvojovy nastroj, ktery vyvojari uz pouzivaji. Lze z toho generovat html stranky. Toto je dokumentace pro vyvojare. (IMHO javadoc ale obecne komentare a poznamky v kodu jsou musthave, at uz nejakou dokumentaci vubec planujete delat nebo ne ;) )Testy jsou z urciteho pohledu taky dokumentace. Dokumentuji, jak urcite casti maji fungovat, jake jsou okrajove podminky, a co to delat nema.Pokud mas na mysli napr user guide, nebo architecture, security, maintenance/support a podobne, tak nato muzes pouzit treba LibreOffice s podporou nastroju pro tvorbu napr. UML diagramu, jako treba class diagram. Tady mas moznosti jako EnterpriseArchitect (placeny, ale existuje i spousta free variant). Je toho spousta. Nebo muzes pouzit nejaka online reseni (i v ramci intranetu), jako napr. wiki, Confluence, E-share, GitHub (muzes mit interni/privatni instalaci, GitHub ma svoji vlastni wiki)
<p>představa, že software s otevřeným zdrojovým kódem je ze své podstaty bezpečnější než software s uzavřeným zdrojovým kódem - nebo opačný pojem - <strong>, je nesmysl. </strong> a když lidé něco takového řeknou to je často jen <a href="http://en.wikipedia.org/wiki/fear,\_uncertainty\_and\_doubt"> fud </a> a nepředstavuje smysluplnou diskusi.</p><p><strong> z tohoto důvodu </strong> musíte diskusi omezit na projekt <em> konkrétní</em>. kus softwaru, který škrábe konkrétní svědění, je vytvořen určeným týmem a má dobře definovanou cílovou skupinu. v takovém konkrétním případě bude možné uvažovat o tom, zda bude open source nebo uzavřený zdroj sloužit projektu nejlépe.</p><p><strong> problém s pitchingem všech implementací „open source“ versus všechny implementace „open source“ spočívá v tom, že se nejedná pouze o porovnání licencí. </strong> v praxi je open source upřednostňován úsilím dobrovolníka musí, a uzavřený zdroj je nejčastější v komerčním úsilí. takže ve skutečnosti porovnáváme:</p><ul> <li>licence.</li> <li>přístup ke zdrojovému kódu.</li> <li>velmi odlišné <a href="http://en.wikipedia.org/wiki/incentive">motivační struktury</a> , pro zisk versus pro zábavu.</li> <li>velmi odlišné situace právní odpovědnosti.</li> <li>různé a divoce se měnící velikosti týmů a týmové dovednosti.</li> <li>atd.</li> </ul><p>chcete-li se pokusit posoudit, jak to všechno funguje pro zabezpečení v celém softwaru vydaném jako otevřený/uzavřený zdroj, jen se zhroutí. stává se to vyjádřením názoru, nikoli skutečností.</p> <p>chtěl bych vidět dynamicky se rozšiřující pole podrobností, takže můžete poskytnout volitelně více podrobností o konkrétních oblastech zkušeností (například fragment kódu nebo složitější informace o projektu), pokud by si zájemce přál více. tímto způsobem si ji udržujete jednoduchou a čistou, ale ukážete jim, že je pod kapotou více, pokud by ji chtěli vidět.</p> <p>důrazně bych vám doporučil, abyste se řídili radami uvedenými v článku derek sivers <a href="http://sivers.org/how2hire">jak najmout programátora, aby se vaše nápady staly</a> . většinu jeho rady lze použít při najímání nezávislého copywritera. nejdůležitější částí (imo) je začít malou částí projektu a najmout více spisovatelů, poté vybrat nejlepší z těch, kdo projekt dokončí.</p> <p>bez licence mohou společnosti a jednotlivci váhat s používáním vašeho kódu, protože jim neudělujete konkrétní práva.</p><p>i když vložíte kód do veřejné domény, udělujete práva k použití. můžete tedy také učinit prohlášení o přijatelném použití, které je pro vás přijatelné.</p><p>bez takového prohlášení nebo licence nic nebrání lidem v používání vašeho kódu způsobem, který považují za vhodný. samozřejmě nic nebrání špatným lidem v porušení vaší licence, ale většina dobrých lidí a společností bude vaše podmínky respektovat, pokud jim řeknete, jaké jsou tyto podmínky.</p><p>stručně řečeno: měli byste mít nějakou formu licence, i když tato licence poskytuje neomezené použití.</p> <p>rozhodně žijete ve smyslu falešné bezpečnosti! sociální inženýrství je dnes stále velmi rozšířené a pochybuji, že se to v průběhu desítek let změní, pokud vůbec.</p><p>zde je několik stručných vysvětlení, proč funguje sociální inženýrství. je těžké pokrýt vše, protože sociální inženýrství je opravdu široké pole.</p><p>některé důvody, proč funguje sociální inženýrství (z knihy citované dole):</p><ul> <li>většina lidí si přeje být zdvořilý, zejména k cizincům</li> <li>profesionálové chtějí vypadat dobře informovaní a inteligentní</li> <li>pokud jste chváleni, budete často mluvit více a prozradit více</li> <li>většina lidí by nelhala kvůli lhaní</li> <li>většina lidí laskavě reaguje na lidi, kteří se zdají být znepokojeni</li> </ul><p><strong> být užitečný </strong></p><p>lidé si obvykle chtějí navzájem pomáhat. rád děláme hezké věci!</p><ul> <li> <p>narazil jsem na recepci ve velké firemní kanceláři s papíry namočenými v kávě. mluvím s recepční a vysvětlím, že mám schůzku na pracovní pohovor za 5 minut, ale právě jsem rozlil kávu na všechny své papíry. pak se zeptám, jestli by recepční mohl být tak sladký, a vytisknout je znovu pro mě s touto usb pamětí, kterou mám.</p> <p>mohlo by to vést ke skutečné infekci pc recepční a mohlo by mi to získat oporu v síti.</p> </li> </ul><p><strong> používání strachu </strong></p><p>strach z neúspěchu nebo nedělání podle pokynů:</p><ul> <li> <p>facebooková stránka ředitele společnosti (john smith) (nebo jakýkoli jiný zdroj informací) ukazuje, že právě odjel na plavbu po dobu 3 týdnů. zavolám sekretářce a velícím hlasem říkám: „ahoj, volá chris. právě jsem opustil telefon s johnem smithem, má velmi dobrý čas na své plavbě se svou ženou carlou a dětmi. nicméně jsme v uprostřed integrace velmi důležitého obchodního systému, a řekl mi, abych vám zavolal, abyste nám mohli pomoci. nemohl volat sám sebe, protože jde o safari, ale to je opravdu naléhavé. vše, co musíte udělat, je vzít usb flash disk, který mu je zaslán v poště a zapojen, spusťte počítač a my jsme hotovi. projekt přežije!</p> <p>děkuji mnohokrát! byla jste skvělá pomoc! jsem si jistý, že vás john smith uzná za tento čin vstřícnosti. "</p> </li> </ul><p><strong> <a href="http://en.wikipedia.org/wiki/norm\_of\_reciprocity">hra na reciproci</a> </strong></p><ul> <li> <p>dveře zavazadlového prostoru. zadržuji pro vás vstupní dveře a rychle za tebou chodím. když otevřete další dveře, což je zabezpečené zabezpečení, zamířím stejným směrem a většina lidí se pokusí splácet užitečnou akci tím, že pro vás dveře opět podrží, čímž se dostanete na místo, kde byste neměli být. bojíte se, že vás chytí? ne. jen říkáš, že je ti líto a že jsi šel špatně.</p> <p>cíl by se téměř cítil povinen držet dveře za vás!</p> </li> </ul><p><strong> využití zvědavosti </strong></p><ul> <li> <p>zkuste hodit 10 usb flash disků na různá místa ve vaší organizaci. nemusíte je umisťovat na příliš zjevná místa. usb by mělo mít automaticky spuštěný domácí program telefonu, abyste viděli, kdy někdo připojí usb flash disk a měl by být teoreticky využit.</p> <p>další verzí tohoto je vyhodit usb flash disky s jediným dokumentem pdf, který se nazývá např. „john smith - norway.pdf“. dokument pdf obsahuje exploat adobe acrobat reader (existuje spousta a poté, co uživatel klikne na dokument, který bude vlastnit. samozřejmě jste se ujistili, že je zneužití přizpůsobeno konkrétní verzi adobe cílové organizace. bude pro většinu lidí přirozené otevřít dokument, aby mohli zkuste usb disk vrátit jeho vlastníkovi.</p> <ul> <li>dalším příkladem zvědavosti (možná jiný termín to vysvětluje lépe) jsou všechny tyto spam maily nebo špatné internetové reklamy, že jste něco vyhráli nebo nigerijský princ vám nabízí spoustu peněz, pokud mu můžete pomoci. jsem si jist, že jste s nimi již obeznámeni, ale jedná se také o útoky na sociální inženýrství a důvod, proč se nezastavili, je, že stále fungují!</li> </ul> </li> </ul><p>to je jen několik příkladů. samozřejmě existuje spousta tun!</p><p>můžeme se také podívat na historické události sociálního inženýrství:</p><p><strong> hbgary </strong></p><p>celý příběh si můžete přečíst <a href="http://arstechnica.com/tech-policy/news/2011/02/anonymous-speaks-the-inside-story-of-the-hbgary-hack.ars/">zde</a> (strana 3 obsahuje část sociálního inženýrství)</p><ul> <li> <p>v loňském roce byl hbgary hacknut. tento útok zahrnoval mnoho různých kroků, ale také aspekt sociálního inženýrství. hacker v krátkosti vyprávěl e-mailový účet společnosti vip) ve společnosti a poslal e-mail administrátorovi cílového systému, který řekl něco podobného: „ahoj johne, v současné době jsem v evropě a poskakuji mezi letišti. můžete mi otevřít ssh na vysoce číslovaném portu pocházejícím z jakékoli ip? potřebuji udělat nějakou práci. “když administrátor dostane tento e-mail, cítí, že je přirozené vyhovět tomuto, když e-mail pochází z důvěryhodného zdroje.</p> <p>ale to není ono! útočník měl heslo k účtu, ale přihlášení nefungovalo! takže pošle e-mailem zpět administrátorovi: „hej znovu, zdá se, že to nefunguje. heslo je stále správné? jaké bylo uživatelské jméno znovu?“. nyní také poskytl skutečné heslo pro systém (útočník to měl z dřívějšího kompromisu jiného systému ve stejném hacku), což útočníkovi poskytlo mnohem větší důvěru správce. správce samozřejmě souhlasí a sdělí útočníkovi své uživatelské jméno.</p> </li> </ul><p>seznam nahoře pochází z knihy " <a href="http://rads.stackoverflow.com/amzn/click/0470639539">sociální inženýrství: umění lidského hackování</a> " a mohu ho velmi doporučit!</p> <blockquote> <p>„musí existovat dobrá metrika, aby bylo možné určit, kdy je vhodné použít rámec.“</p> </blockquote><p>spíš ne. kdyby existovaly dobré metriky pro určení vhodného použití jakékoli technologie, neviděli byste svaté války v jazyce, editoru a metodice.</p><p>skupiny, se kterými jsem spolupracoval, dělají totéž - odhadněte si náklady a přínosy, zvolte nejproduktivnější cestu a doufejte, že mají pravdu. není to strašně vědecké - jedna část intuice, tři části zkušenosti, jedna část náchylnost k marketingu, jedna část mazaný a pět částí hodnotí názor.</p> [Baňka-Security](http://packages.python.org/Flask-Security/) je pravděpodobně nejvíce zralý knihovny k tomu, že, a je pod aktivním vývojem v okamžiku psaní. <p>jednoduchá řešení jsou lepší pro dlouhodobou údržbu. a nejde vždy jen o jazykovou znalost. složitá čára (nebo čáry) vyžaduje určitý čas, i když jste odborníkem na daný jazyk. otevřete soubor a začnete číst: "ok, jednoduché, jednoduché, rozumíte, jo, wtf ?!" váš mozek se zastaví a budete muset zastavit a dešifrovat složitou linii. pokud neexistoval měřitelný a konkrétní důvod této implementace, je to „příliš chytré“.</p><p>zjistit, co se děje, se progresivně zhoršuje, jak složitost roste z chytré metody na chytrou třídu na chytrou strukturu. kromě známých přístupů musíte přijít na myšlenkový proces, který šel do vytvoření „chytrého“ řešení, což může být docela obtížné.</p><p>to znamená, že nerad se vyhýbám vzoru (když je jeho použití oprávněné) jen proto, že mu někdo nemusí rozumět. je na nás jako vývojářích, abychom se neustále učili, a pokud něčemu nerozumíme, je to důvod, proč se to učit, a ne se mu vyhýbat.</p> Upřímně řečeno, já bych jít s sestavení .NET, jak se zdá být jednodušší řešení a těsněji obsahoval řešení, než zahájit nový proces. Některé z důvodů, proč jsem pocit, že způsob, jakým jsou tyto:


1. S nástrojem příkazového řádku, že jste na trh nový proces. Takže je to zcela samostatný proces ID běh a bude probíhat mimo rozsah a aplikační domény vaší stávající aplikace. Veškerá komunikace mezi aplikací a procesu bude přes hranice procesu a bude muset být provedeno buď s telefonem, jakési sdílené paměti, nebo nějaký jiný přístup, který by mohl být těžkopádný (zejména při řešení otázek).
2. Se zahájením nového procesu, jste v podstatě ztratí kontrolu nad tímto procesem z vaší aplikace. Pokud vaše aplikace zemře nebo se vypne, budete muset tento proces výslovně zabít - jinak budete muset úchyty zůstat otevřené soubory uzamčeny, atd.
3. Včetně sestavení .NET v aplikaci umožňuje vše spustit ve stejném kontextu (obecně), který umožňuje lepší komunikaci mezi složkami, snadnější ladění a odstraňování poruch (obecně), a jediný způsob je řízena.
4. Máte trochu větší kontrolu nad kódu. Zahájení procesu je v podstatě black-box - nemáte ponětí, co se děje uvnitř ní. Je pravda, že se sestavení .NET máte podobný black-box scénář, ale vzhledem k tomu, že je ve stejném procesu, může mít nějaké další vhled do toho, jak jsou hovory byly provedeny, kde jsou výjimky být hozen, atd. V podstatě mít trochu větší vhled do složky s sestavení .NET spíše než zahájit nový proces.


To jsou jen některé myšlenky z vrcholu mé hlavy. Doufám, že to pomůže. Máte-li dotazy, dejte mi vědět a já vám zpracovat mé odpovědi. Hodně štěstí!! <p>nedávno jsem byl ve vaší přesné situaci. moje společnost chtěla najmout jiného programátora a konkrétně jsem chtěla někoho, kdo má více zkušeností než já, abych se mohl dál učit a růst.</p><p>z rozhovorů jsem byl nejvíc nervózní, a tak jsem se zeptal <a href="https://softwareengineering.stackexchange.com/q/18371/1130">otázka zde</a> .</p><p>abychom to shrnuli, položte otázky, na které znáte odpověď, souvisejí s problémy, které máte, nebo s problémy, které jste v minulosti vyřešili. nesnažte se klást otázky, které jsou mimo vaši hloubku. buďte upřímní, pokud dotazovaný začne mluvit v termínech, kterým nerozumíte, a požádejte ho, aby vám je vysvětlil. poté, co najmete, s vámi bude spolupracovat a budete chtít někoho, kdo vás může mentorovat.</p><p>ukázalo se to skvěle. najali jsme někoho, kdo má mnohem více zkušeností a znalostí než já, a cítím, že se toho hodně učím.</p><p>řekl bych, že je to pro vás oboustranně výhodná situace. nejhorším scénářem je, že si najmete osobu, kterou najmete, a vy jste získali cenné znalosti, které s ní pracujete.</p>