Technikai dokumentáció írása hogyan

Iroda

Sziasztok!

Van az MS Wordnél jobb eszköz technikai dokumentáció írására?

Ilyen feltételeknek kéne hogy megfeleljen (lehetőleg minél többnek):

  • Annyira részletes dokumentációt kellene írni, ami alapján egy olyan programozó is meg tudja csinálni a feladatot, aki nem érti az egész rendszert és a környezetet sem biztos hogy ismeri. (Wordben nem gond hogy regényt kell írni, mert aránylag kényelmes.)
  • Részfeladatokra lehet bontani a dokumentációt (Wordben kb. fejezetek)
  • Többen is szerkeszthessék egy rendszer dokumentációját (különböző részeit) egy időben. (Wordben lehet több dokumentumra szétszedni, vagy talán az online verzióban van közös szerkesztés)
  • Könnyű legyen egy szabványos kinézetet létrehozni (Wordben is vannak stílusok)
  • A változtatásokat jól lehessen követni (Wordben is van változáskövetés)

A fentieknek megfelelne a TeX, csak abba kicsit sok idő beletanulni.

Ismerem még a Confluence-t, abban van egy wiki rendszer felturbózva, ami nagyjából céges dokumentációra van kihegyezve, végül is az sem rossz.

Nem tudom van-e ezeknél jobb megoldás.

  • 1874 megtekintés

( SzBlackY | 2021. 02. 11., cs – 18:58 )

Bármi, ami Markdown-t kezel? Akár csak egy git/svn/akármi repó / fájl share és egy csomó md fájl.

BlackY

"Gyakran hasznos ugyanis, ha számlálni tudjuk, hányszor futott le már egy végtelenciklus." (haroldking)

+1 az asciidoc-ra, nagyon jol integralhato, lehet benne kodreszletekre hivatkozni. Sokkal tobb funckioja van mint egy egyszeru markdown-nak, szepen modularizalhato. Most eppen enduser es technikai doksit rakunk ossze antora-val, van benne site epites, verziokezeles, stb ... Nagyon profi, meg ugy is hogy most tanuljuk. 

Végigfutottam az antorán, eddig nem ismertem. Úgy látom annyit tud, hogy forráskezelő rendszerekből (mint a git) le tudja húzni a dokumentáció forrását és asciidoctorral beformázva, témázható weblapokat csinál.

Lehet hogy jó lesz valamire, még tanulmányoznom kell.

Asciidoctort javallanék inkább...

Hát nem tudom... Az eddigi hozzászólásokban már dicsérték többen, ezért kicsit belenéztem.

Ha ezzel ne adj isten olyan dokumentációt kéne készíteni, ami nyomokban matekot/képleteket tartalmaz, nem nagyon örülnék. Az egy dolog, hogy könnyű beírni a forrásba, de a megjelenítése...

A HTML outputban használható a  MathJax, ez teljesen rendben van. Minden más output - amit az Asciidoctor Mathematical generál - beágyazott képekként tartalmazza a képleteket. Ez már a 90-es években sem volt a technika csúcsa. Ha valaki igényes(ebb) dokumentációt emleget, ezt már azért mégse így kéne a 21. században.

az, hogy az a három db képlet kép lesz, imho bőven belefér a good enoughba nekem.

Hát igen, lehet hogy igazad van...

Nekem még olyan múltszázadi elképzeléseim vannak, hogy a dokumentáció az, ami megvan kinyomtatva/lefűzve vastag dossziékban/könyvekben (is).  Meg olyan becsípődéseim, hogy - bár a papír mindent elbír - azokon a lapokon korrekt, a magyar helyesírás, tipográfia és stilisztika szabályainak megfelelő szöveg van.*

Többek között esztétikusan tördelt, sorkizárt, helyesen elválasztott sorokkal, jól elhelyezett, olvasható ábrákkal és táblázatokkal.

Ennek semmi köze ahhoz, hogy miről szól a dokumentáció, milyen eszközzel készült, használtak-e verziókövető rendszert, hányféle outputot tud a rendszer, stb.

A nyelvi és szakmai igényesség szintjét mindig lehet kicsit lejjebb tenni - no de hol a határ? Ha nincs elég pénz/idő/tudás, nem baj, ha a végeredmény "kicsit sárgább, savanyú", mint a magyar narancs?

* És ezeken az apróbb nüanszokon bizony elbukhatnak az újabb csilivili TeX leszármazottak is, amikben (korlátozott) ismereteim szerint nem tart ott a magyar nyelvi támogatás, mint a LaTeX-ben a sok évi munkával készült, folyamatosan fejlesztett magyar.ldf segítségével.

Itt most nem az Unicode támogatásáról, egyszerű és nagyszerű fontkiválasztásról, stb. beszélek, hanem alapvető helyesírási és tipográfiai szabályokról. Persze örömmel veszem, ha valaki megcáfol, de ebből nem sok jóra lehet számítani:

    [xxx@localhost Magyar-ldf]$ wc magyar.ldf.2019.01.14

    5901 19006 251992 magyar.ldf.2019.01.14

    [xxx@localhost polyglossia]$ wc gloss-hungarian.ldf

    300 504 10002 gloss-hungarian.ldf

Egyfelől erre plusz egy, minden szavával egyetértek (még ha látom is, hogy egyre inkább mindenki viszi lefelé a küszöböt :( )

Másfelől: a jó dokumentáció az, ami naprakész és használható :) Ha minden egyes változtatásnál újra kellene nyomtatni a dokumentációt, egy idő után jönnének az Entek és kikérnék maguknak, így viszont ha csak nyomtatott dokumentációban gondolkodunk, az egy idő után nem lesz naprakész, tehát nem lesz jó. (a papír vs. digitális használhatóságnál... egy Control + F-et még mindig hiányolok a nyomtatott anyagokból :) )

De egy projekt lezárásaként készült, kvázi (abban a keretben) már végleges doksinál teljesen egyetértek az igényesség igényével.

BlackY

"Gyakran hasznos ugyanis, ha számlálni tudjuk, hányszor futott le már egy végtelenciklus." (haroldking)

De egy projekt lezárásaként készült, kvázi (abban a keretben) már végleges doksinál teljesen egyetértek az igényesség igényével.

Továbbra is teljesen egyetértünk ;-) Csak hát az igényesség nem úgy megy, hogy majd a végén igényesek leszünk, addig meg hagy szóljon!

Egyszer lehetne pl. egy nagyobb mintán (néhány ezer oldal?) csinálni egy statisztikát, hogy az "egyszerűbb, gyorsabban legenerált" (nem elválasztott, nem sorkizárt) dokumentációs szöveg mennyivel hosszabb (~mennyivel tovább tart elolvasni). No de kit érdekel ilyesmi...

Itt a vége, igyekszem lelőni magam.

hogy a dokumentáció az, ami megvan kinyomtatva/lefűzve vastag dossziékban/könyvekben

szvsz ez már 10 évvel ezelőtt is elavult elvárás volt, és tipikuan az ilyen dokumentációkat SENKI nem olvassa, csak idő és pénzkidobás már az elkészítése is. A kinyomtatása pedig kizárólag papír pocsékolás.

Nem beszélve arról, hogy igen hamar (kb az első bugfix release-nél) elavul.

És akkor a "classification" még szóba sem került: sok helyen van olyan szabály, hogy amit kinyomtatttak, annak egyből csökken a bizalmassági szintje.

 

Az IT-ben a okumentációnak akkor van értelme, ha az használható. Azaz könnyen és bárhonnan elérhető, amikor épp szükség van rá. A papír-ra optimalizált formátumok amúgy kifejezetten nem jók informatikai dokumentációra.

(legtöbbször már egy szimpla képernyőkép is értékelhetetlen ebben a formában)

 

a magyar helyesírás, tipográfia és stilisztika szabályainak megfelelő szöveg van

Hát... a magyar piac elég szűk réteg :) igen nagy luxus ennek megfelő dokumentációt igényelni.

nálunk 100-ból 99 dokumentáció angolul készül. És hát lássuk be, a gyakorlatban a kutyát sem érdekli, hogy Brit, vagy USA nyelvtani és tipográfiai szabályoknak fele-e meg. Sőt, már a 'papír' formátum sem elég multinaciónális, mert minden kontinensen más a megszokott méret(arány).

 

Ennek semmi köze ahhoz, hogy miről szól a dokumentáció

A fentiekkel érvelve - és a gyakorlatban látva, de bizony hogy van. Mert egy építészeti dosinak, egy bólcsész szakdolgozatnak, vagy egy IT technikai dokumentációnak teljesen másak az igényei....

 

szerintem.

zrubi.hu

Egyetértek. A dokumentációt az minősíti hogy hányan és hányszor olvassák és milyen gyorsan találják meg benne azt amit keresnek. Sorry de ebből a szempontból a tipográfia másodlagos. Egyébként ebből a szempontból a Confluence szerintem egész jól kinéző dolgokat csinál minimális erőforrásból.

 

El kell választani a tartalom struktúrát (és annak hasznosságát, jóságát) a megjelenítéstől.

A megjelenítést amúgy egész jól lehet template-ezni Confluence-ben is, kb. amit fontokkal, html-el meg lehet oldani azt meg tudod csinálni.

Gábriel Ákos

Nézd, én is nagyon szeretek ilyesmiken lovagolni, egyet is ért a lelkem veled gyak mindenben*, ha valaki kockával ki akarok tolni, megmondom, hogy olvasson utána a font kerningnek, hogy utána hónapokig fájjon gyak. a teljes internet :)

De egyrészt feladathoz az eszközt: A doksik, amikről a topicnyitó beszélt alapvetően arra valóak, hogy összerakják a fejlesztők belőle a szoftvert. Ezek jellemzően nem arra készülnek, hogy lefűzzék őket, egy szoftver nem egy híd. A fejlesztők remekül elvannak ligatúrák nélkül is, sokkal fontosabb, hogy ezek időben készüljenek, és a tartalmuk rendben legyen. A usernek szóló dokumentációkban pedig -- bár itt nyilván fontosabb a korrekt kinézet, --  kell azért végiggondolni, hogy oda mi kell. Nagyon érdemes például egyszer egy jó tech writerrel beszélgetni arról, hogy amikor te azt gondolod, hogy szép, kerek, stilisztikailag jó, szépirodalmi igényességű doksit írsz, akkor valójában hányféleképpen baszol ki a userekkel :)

Illetve, ha már userek, akkor másrészt, feladathoz az eszközt :) A tex egy dologban jó nagyon. Igényes papír tipográfiát csinálni. Egy átlagos szoftver dokumentációban ez max egy dolog, jó eséllyel nem is a legfontosabb, de tuti, hogy kell mellé normálisan kinéző online doksi oldal, jó eséllyel kellhet mellé windowsos help, offline használható html, man page, átfedésben kell neki lenni pl a beépített "helppel". Na, ezekben a tex már messze nem olyan jó.

Harmadrészt ne csináljunk már úgy, mintha bármi, ami nem texel van, az teljesen igénytelen lenne. Kis állítgatással egy modern word teljesen kultur tipográfiát tud magából kitolni, és igaz ez a többi eszközre is nagyrészt. Konkrét példánál, ami valóban fájó kissé az az elválasztás, bár ha jól láttam, került már support a pdfbe. Illetve igen, "magyar tipográfiára" gyanús, hogy nehéz kényszeríteni.

* Az egyetlen dolog, ami mindig is zavart, az a "jól elhelyezett" táblázat, ami tipikus fordítva ülés a lovon. Nem floatoljuk el a táblázatot három oldallal hátrébb, az ábrát sem. Csodálatos volna, ha pl egy user doksinál a kattints ide szemléltető képe hátrább lenne, mint ahol a helye van, hogy szebb legyen az oldaltükör.

Egyetértek. Ez a legegyszerűbb, ami tényleg rugalmas, a markdown-t könnyű megtanulni, csak írni kell. Annyi, hogy én a Jakyll-t nem használtam még, így én pandoc-ot tudom javasolni, azzal átnyomni át amolyan Wiki-szerű statikus html-be, és verziókezelésre git, arra a célra jobb nincs. Technikai dokumentációnál a szedés tipográfiája nem olyan fontos, hogy követelmény legyen a TeX vagy LaTeX, de lehet ennek ellenére abban is.

Megjegyzés: Word-ben semmiképp. Akkor inkább LibreOffice Writer is jobb, sokkal szebb formázásokat tud egyébként is tipográfiailag, nyílt, nincs vendor lock-in, stb.. Wordnek egy előnye lenne, ez a verziókövetés, meg hogy többen is dolgozhatnak a dokumentumon, de mint írtam, ezt a két követelményt a git egyszerre váltja ki amúgy is.

“The world runs on Excel spreadsheets.” (Dylan Beattie)

( apal v | 2021. 02. 11., cs – 19:06 )

Pedig tenyleg ez a leghatekonyabb: latex + overleaf. Vsz egy tech dokumentacional pl az abra/grafikon/tablazatkeszites visz majd az idot, nem az hogy beird hogy \section vagy \tableofcontents. 

( gabrielakos v | 2021. 02. 11., cs – 20:45 )

Confluence szerintem teljesen jó megoldás erre.

Gábriel Ákos

A Confluence-szel az a probléma, hogy a dokumentáció nem lesz mozgatható, legfeljebb PDF-be tudod kiexportálni, és annyi, de az eredeti, szerkeszthető, verziózott változat a Confluence-től elválaszthatatlan. Ha gitben verziózol egy Markdown file-t, akkor nincs ilyen probléma, azt csinálsz vele, amit akarsz.

Ráadásul, ha van ilyen igény, akkor magával a termékkel együtt is verziózható, tehát mindig a megfelelő dokumentáció látható egy adott állapothoz, sőt akár a commit része lehet a doksi változtatása is, ha egy kód változás kihat a dokumentációra.

( kantal | 2021. 02. 11., cs – 20:50 )

Pandoc's Markdown, egy-két óra alatt megtanulható

A fejezeteket külön-külön írhatod, amiket azután a pandoc programmal egyetlen epub-ba vagy pdf-be össze lehet gyúrni.  (Az íráshoz természetesen nem kell a pandoc program, csak a konvertáláshoz). Tehetsz bele LaTeX-et is, és még sok minden mást is ért. (Éppen írok egy rövid ismertetőt róla, talán holnap készen is leszek vele.)

Ahogy írták, a GitHub-ot vagy GitLab-ot is lehet használni, és akkor ugyanazon a fejezeten többen is dolgozhatnak.

eutlantis

( BlackCode | 2021. 02. 11., cs – 20:52 )

Notable-t használok a dokumentációk készítésére, amibe mermaid-js is integrálva van, így egyszerűen tudok akár brainstorming alatt flowchartokat, és egyéb diagramokat összedobni (ezt későbbiekben akár draw.io-ba is importálni lehet) anélkül, hogy egerezni kellene. Egy git repóba verziókezelve könnyen megoszthatóvá tehető. A fejlesztője a jövőben beépített szinkronizációt és verziókövetést is szeretne implementálni bele.

Az automatikusan mentett .md doksikat közvetlenül pdf-be, vagy html-be is lehet exportálni.

( sz332 v | 2021. 02. 11., cs – 21:04 )

Ha csak dokumentációt akarsz írni, akkor erre egy tetszőleges online szerkeszthető eszköz (online word, google docs, confluence, stb.) megoldja.

 Ha viszont korrekt specifikációt akarsz készíteni, akkor praktikus valamilyen model alapú megoldást csinálni, hogy ne csak rajzaid legyenek hanem modelljeid, ezek minden előnyével együtt (requirement modellezés, use case/story modellezés, folyamatok, állapotok, interfészek modellezése, validáció, transzformáció, stb.). Erre van egy rakás eszköz, én a NoMagic cég termékeit, vagy a Visual Paradigm-ot tudnám javasolni (de nyilván ezek csak eszközök amelyek megkönnyítik a munkát).

( msandor v | 2021. 02. 12., p – 07:35 )

  • Annyira részletes dokumentációt kellene írni, ami alapján egy olyan programozó is meg tudja csinálni a feladatot, aki nem érti az egész rendszert és a környezetet sem biztos hogy ismeri. (Wordben nem gond hogy regényt kell írni, mert aránylag kényelmes.)

szerintem ez nem platform függő

  • Részfeladatokra lehet bontani a dokumentációt (Wordben kb. fejezetek)
  • Többen is szerkeszthessék egy rendszer dokumentációját (különböző részeit) egy időben. (Wordben lehet több dokumentumra szétszedni, vagy talán az online verzióban van közös szerkesztés)
  • Könnyű legyen egy szabványos kinézetet létrehozni (Wordben is vannak stílusok)
  • A változtatásokat jól lehessen követni (Wordben is van változáskövetés)

Mióta az eszemet tudom, dokuwikiben tartom nyilván minden tudásomat. Az összes feltételnek megfelel, legfeljebb nem ez a legprofibb választás.

Elmondom miért szeretem, és használjuk a dokuwikit a cégnél, pedig van confluenc-ünk nekünk is:

  • ingyenes, nyílt forráskód
  • faék egyszerű üzemeltetni, egy tetszőleges webszerver kell neki php-val, és ennyi
  • plain textben tárolja az adatokat, tehát vész (DR) esetén működő webszerver nélkül is lehet doksit olvasni (less valami.txt)
  • a funkcióit tetszőlegesen lehet bővíteni modulokkal
  • remek a jogosultság kezelése (ACL), tud LDAP-ból is authentikálni
  • egyszerre lehet nyílt és zárt wikit csinálni belőle (pl a public névteret bejelentkezés nélkül is megtekintheti bárki)
  • nagyon könnyű a nyelvezete, a tipikus formázások kódjait fejből tudom, ami ritkán kell, azt meg a súgója megmutatja
  • kevés erőforrásra van szüksége (RAM, CPU, HDD)

( ngm.hun | 2021. 02. 12., p – 08:54 )

Köszönöm mindenkinek a válaszokat. Van néhány eszköz, amit érdemes jobban megnéznem.

( sigellef | 2021. 02. 12., p – 09:15 )

html? szépen, logikusan mappákba rendezve? Eszköz: text editor + bengésző.

-fs-
Az olyan tárgyakat, amik képesek az mc futtatására, munkaeszköznek nevezzük.

( zrubi v | 2021. 02. 12., p – 11:01 )

Szerkesztve: 2021. 02. 12., p – 11:02

Hát, a Word-nél bármi jobb technikai dokumentcáció esetén :D

~20 éves pályafutásom alatt egy kezemen megszámolható mennyiségű dokist csináltam word-ben. Azt is csak "kényszerből" ;)

 

Én annó csináltam LaTeX alapon egy rendszert ami előre megírt modulokat rakott össze (a szolgáltatás összetételétől függően) tehát megírni/frissíteni csak a modulokat kellett egyesével. Ezt a "konfig generátor" pakolta össze, a végeredményt pedig .pdf-be exportálva egyből "customer ready" végeredményt produkált.

Ma már ugyan ezt a process-t lehet bármelyik markdonw nyelvre is alkalmazni, könnyebb megtanulni, de nyilván limitáltabb kicsit.

markdown + git kombo adja magát, főleg ha kódot/konfigot amúgy is ott tartod.

 

Még felhasználóbarátabb (cserébe kevésbé scriptelhető) bármilyen wiki. Ez akkor jön szóba, ha amúgy is használtok wikit.

Ha új wiki kell, és nem kell ágyú, akkor:

- docuwiki (web szerver + php)

- mdwiki (static web szerver elég)

mindkettő egyszerű markdown alapú, szóval clear text -> könnyen scripelhető, verzió követhető, könnyen írható/olvasható.

 

szerintem.

zrubi.hu

( viraghj v | 2021. 02. 12., p – 20:35 )

A kibicnek semmi sem drága...

Az eddigi hozzászólások kimondva-kimondatlanul arra koncentráltak, hogy milyen eszközökkel legkönnyebb elkészíteni a dokumentációt. Ok, a Markdown alapú megoldások lehetnek faék egyszerűségűek, 5 perc alatt megtanulhatók.

De ha komolyabb dokumentációról van szó, nem árt különféle jegyzékeket, indexeket készíteni (pl. tartalomjegyzék, ábrajegyzék, algoritmusok jegyzéke, irodalomjegyzék, szójegyzék, stb.) meg tisztességes (kereszt)hivatkozásokat betenni a dokumentumokba. LaTeX alapon ez nem nagy kunszt, de nem tudom, hogyan segítene pl. ebben  a Markdown...

Arra is kíváncsi lennék pl. hogyan lehetne két forráskód listát egymás mellett formázva megjeleníteni - ami egy dokumentáció készítése közben éppenséggel reális igény lehet.

Szóval az egy pozitívum, hogy a Markdown-ba lehet LaTeX-et beágyazni, no de akkor miért ne legyen csak LaTeX?

Ha meg komolyan vesszük az első követelményt:

"Annyira részletes dokumentációt kellene írni, ami alapján egy olyan programozó is meg tudja csinálni a feladatot, aki nem érti az egész rendszert és a környezetet sem biztos hogy ismeri."

akkor lehet, hogy a "literate programming" filozófia szerint olyan eszközöket kellene használni, amikkel precízen leírható a kód és a dokumentáció kapcsolata, illetve közös forrásból generálható a kód és a dokumentáció.

> Szóval az egy pozitívum, hogy a Markdown-ba lehet LaTeX-et beágyazni, no de akkor miért ne legyen csak LaTeX?

Bár eléggé csak szőr mentén ismerem, meg ritkán használom, de kifejezetten szeretem a latexet. Ennek ellenére szerintem technikai  / termék dokumentációt nem nagyon írnék benne. Az ok egyszerű: elég bonyolult, és nem kifejezetten erre való[1]. Emiatt egyrészt viszonylag sok időt kell jó eséllyel eltölteni, hogy valami alapot faragj, és output oldalon sem igazán rózsás a helyzet. HTML pl ugye. (ne keresd meg, biztosan lehet valahogy)

Ráadásul már egyszerűbb formázásoknál is töri a  nyers olvashatóságot, meg az írás flowját. Ez természetesen durván egyén és megszokás függő, én akármi wysiwygben sokkal lassabban írok, nagyon lendít rajtam ha simán csak text gépelek, és ez már latexben is rosszabb. Egy sima lista is \begin{itemize} \item ... \item \end{itemize}, ehhez képest az, hogy enter, * szöveg, ha be kell húzni akkor ** sokkal kényelmesebb.

Abban egyetértünk, hogy a markdown szerintem is nagyon hamar karcsú tud lenni, feljebb is ezért javasoltam az asciidoctort. Nagyon sok mindent tud alapból, amit az ember egy doksinál egyébként használna, kényelmes, sok féle listák, adomontionok, mindenféle blokkok, színezett, számozható megjegyzésekkel kódok pl (ahol az annotáció pl nem jelölődik ki, hogy copypaste friendly legyen), használható táblázatok, amiknek a belsejében is könnyen működnek az extra lehetőségek, inline generált mindenféle diagramok, nyilván van mindenféle list of izéhozé (bár szerintem nagyon ritka kivételtől eltekintve ember nem nézett még list of figurest pl) stb, fogyasztható pdf és html.

Természetesen ezt mind meg lehet csinálni latexban is, sőt, még sokkal többet is, és természetesen a pdf a közelébe nem jön egy jó latex rendernek, de bőven vállalható, cserébe sokkal gyorsabb tanulási görbe, imho sokkal jobb writing élmény, és egy direkt doksikra kihegyezett toolbox van benne alapból.

Ha ennél több kell (pl mert output oldalon még ez is lacking azért) akkor meg a docbook toolchain, bár abban írni azért elég fájdalmas imho. (Alternatívának meg esetleg a restrucutred text).

[1]: tudom tudom, az összes tudós hülye, mert ebben írja, nem értek hozzá, minek szólom le. Szóval értem, ezzel együtt az alapvetően még mindig egy jó automata szedőrendszer, és ha hozzá akarsz nyúlni valamihez, akkor elég sokat kell ilyesmivel cseszni. És in real life egyébként kevésbé érdekes, a "good enough" az üzletileg reális cél.

akár :-)

sőt! Lásd https://www.google.com/search?client=firefox-b-d&q=LyX+literate+programming

2.5  Typesetting tools

ChkTeX Homepage - performs typographical checking.
LyX can use ChkTeX as an aid to find common typograhical errors in your document.
NoWeb - literate programming.
Use LyX to write programs whose documentation and manuals are included in the program.
Sweave - literate programming.
Tool that allows to embed the R code for complete data analyses in latex documents.
Knitr - literate programming.
A comprehensive R package derived from Sweave with a different design that includes code formatting, highlighting, caching, fine control of graphics, conditional evaluation, multiple markup formats and other features.
The SGMLtools homepage - DocBook support (only for LyX < 2.4)
If you want to create documents using the LinuxDOC DTD that is used for the Linux Documentation Project to create documents in a variety of different formats, you'll need to get the SGMLtools. From LyX 2.4 onward we produce Docbook version 5 (XML based) which does not need SGMLtools.

Az a jó ezekben a plain text alapú szedési és leíróformátumokban, hogy mindegy miben írja, mert később is konvertálható egyik a másikba, és erőforrásuk se nagy, akár egy Pentium 2-őn is lenyomhatók egy plain text editorban. Sima TeX-variánsban is lehet írni, pl. XeTeX, LuaTeX, és itt TeX-en nem a LaTeX-et értem, hanem az annak az alapjául szolgáló még egyszerűbb nyelvet. De ha valaki keményebb, mint Chuck Norris, Bruce Lee és John Rambo összeadva, akkor groff-ban is csinálhatja, de az már tényleg olyan, mintha abakuszon tologatná valaki a biteket. Vagy ha a céges CMS rendszerük kezeli, akkor akár BBCode-ban, vagy hasonlóban. Bármiben, amiben az illető kényelmesen mozog.

A markdown igaz, hogy limitált, de elég a feladatra. Technikai dokumentációnál nem kell annyira igényes szedés, nem bölcsészeknek lesz, hogy ligatúrákon meg sorvégek és margók optikai egyenességén sznobkodjanak. Ennek ellenére a markdown - HTM5 konverzió után a HTML is jól tud kinézni, soft hyphen, modern fontok, Unicode, ligatúrák, OpenType feature-ök, SVG grafika, stb. segítségével, belefér az általad is írt good enough-ba, lesz olyan szintű, mintha valaki Word-ben írta volna, igaz ehhez kicsit csalni kell, és a markdown-ba több mindent is bele kell foglalni, vagy a HTML5-re konvártálás után bele kell nyúlkálni vagy custom CSS-ezni. Cserébe még dinamikus tördelésű is, bármilyen eszközre és kijelzőméretre jól skálázódik, és még spéci reader szoftvert sem kell a megnézéséhez telepíteni. Mert ha TeX-variánssal csinálja az ember, akkor statikus tördelésű, csak nyomtatásban meg nagy felbontású kijelzőn fog jól kinézni, csak így lesz könnyen olvasható.

A markdown csak azért népszerű, mert az is már good enough a legtöbb esetben, és rettenet könnyű megtanulni, pár perc egy sablon alapján, és a benne lévő tag-ek nem zavarják az emberi nyers/szabad olvasást, természetes írást, a text editor spellcheking funkcióját, stb.. Nyilván cserében limitáltabb, mint a komolyabb formátumok, de valamit valamiért. Meg a markdown annyira egyszerű, hogy lényegében egy végoptimum fokos megoldás, aminél egyszerűbbet már nem lehet kitalálni, így elég egyszer megtanulni, és nem úgy van vele az ember, hogy most ez a hájp, és majd 5 év múlva elavul, és mást kell tolni helyette.

Ezt az asciidoctort nem ismerem mondjuk, feltételezem ez is valami plain text alapú leírónyelves megoldás. Tényleg sok minden szóba jön, ezeknek a nyílt formátumoknak nagy a rugalmassága. Még a túlzott igényesség sem kell, sok RFC meg annál komolyabb szabvány a mai napig teljesen formázatlan plain text-ben van megírva, némelyik fix 80 karakteres sortöréssel ráadásul. Ez tényleg az a műfaj, hogy a komolyságát nem a formai külsőségek adják, hanem a jó tagolás és lényegre törő nyelvi megfogalmazás.

“The world runs on Excel spreadsheets.” (Dylan Beattie)

> A markdown igaz, hogy limitált, de elég a feladatra. 

Hát, én szoktam technikai doksikat írni, és elég sokszor nem, nem elég. A common markban még egy istenverte táblázat sincs, nem hogy még szélességet is lehessen befolyásolni, nem lehet érdemben kontrollálni mondjuk a sorszámozást, a corssreferenceket, nincsenek benne változók, csak hogy azokat említsem, amik nagyon hamar előjönnek. A mindenféle text -> diagram generálók inlineolhatóan elérhető beépített garmadája is sokszor hasznos.

Arról nem beszélve, hogy van a markdownnak vagy 5 elterjedt dialektusa.

> Ezt az asciidoctort nem ismerem mondjuk, feltételezem ez is valami plain text alapú leírónyelves megoldás

Nézz rá, egyrészt kicsit hihetőbb lenne a mondanivalód, ha legalább megnézted volna, miről beszélek, másrészt tetszeni fog szerintem, ilyen szempontból markdown on steroids. Csak tudja azt, hogy nem kell konvertálás után kicsit belenyúlkálni, meg nem html snippleteket kell a közepébe írni, ha valami nincs benne, adja a fordító toolchaint, adja az értelmes includeokat,  nem neked kell hákolni valamit, ami majd előállítja a doksit, megmutatja, hogy ha akarod, hogyan kell custom cssezni, meg a headereket. Nem azért trúváj, mert sokkal szebbre renderelődik, mint egy markdown htmlbe (nyilván kb ugyanazt tudja), vagy sokkal flexibilisebb mint egy latex (nyilván nem), esetleg szebb pdfet csinál (nyilván nem) hanem az, hogy ez készen van. Általában annyi a teendőd, hogy megkeresed a referenceben, ha valami kicsit extrábbat akarsz, és egyszerűen begépeled, nem kell spanyolviaszt feltalálnod. Természetesen egy kicsit rosszabb a learning curve, de ha rendszeresen írsz, vagy karban kell tartani valami doksit, akkor eléggé kifizetődik.

A túl sok ábra, diagram az minden dokumentációban szívás, és nehéz megoldani plain text alapon, még az SVG van hozzá a legközelebb, de már az se annyira olvasható folyószövegben, megtöri a szabad írást.

A kolléga ráadásul programozós dokumentációban keresi, ahhoz túl sok ábra nem szokott tartozni. Az, hogy pont nem ismerek egy általad ajánlott megoldást, az nem von le a véleményem szakmai értékéből. Nyilván nem ismerhetek mindent, annyiféle megoldás van. Eleve nem is vitattam, hogy alkalmas lehet a feladatra, meg nem én keresek toolokat, hanem a topikindító, így nem tartom kötelességemnek, hogy mindent kipróbáljak és ismerjek. Nekem, ha ilyen technikai doksit kell csinálni, megvan rá az eszköztáram, HTML5, pandoc markdown to HTML5, XeTeX to pdf.

A standard markdown-ban meg kb. semmi sincs. Tud egy-két alap formázást, vastaggal, dőlttel szedés, függőleges vonal, néhány heading szint, verbatim code, link-kép, kézi lista, és kifújt. Semmifelé szövegigazítós csicsa (pl. sorkizárás, középre zárás, ezek CSS-ben pótolhatók később), semmi dinamikus tartalom, semmi változó, semmi automatikus számozás, mivel nem erre lett kitalálva. Akinek erre van igénye, az komolyabb nyelven írja. De ezek a hiányosságok megoldhatók kézzel, meg tartalomszervezéssel is, pl. crossreference-t nem sorszám alapján hivatkozol, hanem linkként, meg címkékkel, amit viszont a markdown tud. Néhány markdown dialektus, mint a pandoc, meg a gitlab/github, tudnak extrákat, de azok sem arra valók, hogy LaTeX szintű formázásokat meg mindenféle automatizált jegyzéket meg mindent hozzál létre. Vagyis azt is tudják, de ahhoz markdownon kívüli kódrészeket is be kell ágyazni a dokumentumba, a pandoc markdownban változókat is kezel, akármilyen nyelven, amihez fent van interpreter, csak ha ilyeneket kezd el valaki a markdown doksijába ágyazni, akkor szerintem a markdown értelme, egyszerűsége veszik oda, és nem volt értelme nekiállni ebben a formátumban. Kicsit olyan ez, mintha valaki magas szintű nyelven írt kódban elkezd túl sok ASM betétet beszúrni.

“The world runs on Excel spreadsheets.” (Dylan Beattie)

> A túl sok ábra, diagram az minden dokumentációban szívás, és nehéz megoldani plain text alapon, még az SVG van hozzá a legközelebb, de már az se annyira olvasható folyószövegben, megtöri a szabad írást.

Jó ábrát rajzolni mindig szívás. De azért ha megnézel mondjuk egy blockdiagot, vagy mermaidot, akkor látni fogod, hogy ezek egyrészt viszonylag olvashatóak, másrészt -- ami szerintem sokkal fontosabb -- adat szemantikát írnak le, sokkal jobban változáskezelhetőek, illetve bizonyos esetekben kicsit gyorsabb elfogadható kinézetet csiholni.

> A kolléga ráadásul programozós dokumentációban keresi, ahhoz túl sok ábra nem szokott tartozni

Hálózati diagramok, osztály diagrmok, adatszerkezet diagramok, packet diagramok, adatbázis sémák, állapotgépek, sequence diagramok, activity diagramok, user journeyk, uml... Valóban ritkán vannak, mert lassú őket megrajzolni :)

> Az, hogy pont nem ismerek egy általad ajánlott megoldást, az nem von le a véleményem szakmai értékéből. Nyilván nem ismerhetek mindent, annyiféle megoldás van

Önmagában nem, csak ha valamire reagálsz, nem árt tudni, hogy legalább nagyjából mire, mer pl rájöhettél volna, hogy pont azért javaslom markdown helyett, mert a lentiekből egy csomó mindent nem kell megoldani.

> A standard markdown-ban meg kb. semmi sincs.

Hát ez az. Szóval vagy írsz valami dialektusban a 10 féle közül, vagy nagyon nem sok mindent írsz. Nem annyira robusztus megoldás.

> Vagyis azt is tudják, de ahhoz markdownon kívüli kódrészeket is be kell ágyazni a dokumentumba, a pandoc markdownban változókat is kezel, akármilyen nyelven, amihez fent van interpreter, csak ha ilyeneket kezd el valaki a markdown doksijába ágyazni, akkor szerintem a markdown értelme, egyszerűsége veszik oda, és nem volt értelme nekiállni ebben a formátumban

Ezt félreértetted. Egyszerűen arról van szó beleírhatod, hogy {product} meg {component}, meg {version}, és utána ezeket egy helyen tudod basztatni, mindenhol pont ugyanúgy lesznek leírva, ilyesmi.

( tygryss | 2021. 02. 13., szo – 00:04 )

Egyértelműen LaTeX. Több okból is. Ott elkülönűl a formázás a tartalomtól. Szóval előre le lehet gyártani a cégre jellemző formázást. Ha túlnézünk a pdflate-en akkor ott van a LuaTex, XeLatex, akkor szinte akármit meg lehet szépen csinálni. 

- Nagyon pygmentel nagyon szép source code highlightingot is be lehet hozni.

- Mivel sima text file ezért könnyű scriptet írni, ami legyártya a vázat, pl ha dokumentálod, hogy melyik függvény mit csinál, azokat ki lehet tolni előzőleg scriptel és csak a magyarázatot kell kézzel beírni.

- Pl ábrákat is simán lehet bele generáltatni, pl ha benchmark-ok adataiból csinálsz chart-ot, akkor azt rengeteg formátumba lehet beolvastatni, egyes rendszerek akár TIKZ-be is tudnak menteni. 

Nyelv specifikus, de vannak programnyelvek, amik képesek egy kapcsolóval az output-ot LaTeX-es formátumba kitolni. 

pár érdekesebb videó, hogy pl Julia, Latex kapcsolatáról, de ha jól tudom python-al is van ilyen, gondolatébresztőnek jó lehet. 

https://www.youtube.com/watch?v=ofWy5kaZU3g&t

https://www.youtube.com/watch?v=wpV0Nz-93Hk

( gabrielakos v | 2021. 02. 13., szo – 08:21 )

Ahogy itt a kommenteket elnézem eldöntheted hogy a doksiírást szuperigényesen akarod megtanulni (akkor latex és társai) vagy a feladatot akarod elvégezni (akkor markdown, confluence, stb.)

Gábriel Ákos

Az igényes relatív fogalom, de néha az igénytelenségnek ára van.

Ha pl. egy dokumentációban azt olvasom, hogy

Az installálás során előforduló hibaüzeneteket az 6. táblázat tartalmazza, ...

akkor több eset lehetséges:

1 - tényleg ott van, csak a szerző (vagy az általa használt eszköz) leszarja az egyeztetést

2 - szerkesztés közben pl. fölcserélték a táblázatokat, és sem a névelő, sem a sorszám nem stimmel; lehet lapozgatni, vagy a megfelelő jegyzékben keresgélni - már ha van ilyen.

Ilyesmi a LaTeX-hel simán (automatikusan) kezelhető.

"Az installálás során előforduló hibaüzeneteket az 6. táblázat tartalmazza, ..."

Minek verset írni hozzá, simán odatenni a táblázatot, aminek a címe az hogy "Az installálás során előforduló hibaüzenetek".

Sajnos sok doksiban túl sok a szöveg, és nem azért mert szájbarágósan magyaráz, hanem egyszerűen sok benne a felesleges süketelés.

-fs-
Az olyan tárgyakat, amik képesek az mc futtatására, munkaeszköznek nevezzük.

... simán odatenni a táblázatot, aminek a címe az...

Bár megígértem, hogy nem szólok hozzá, de mégis megkérdem a T. Kollégát, "versírás" helyett hogyan oldaná meg azt a szerfölött bonyolult helyzetet, amikor az adott táblázatra a dokumentum kettő, vagy horribile dictu! ennél is több helyén szeretnénk hivatkozni ;-)

Mit jelent ilyenkor az odatenni?

Miért kéne hivatkozni rá? Leírni pontról pontra az installálás ideális menetét, utána jöhetnek táblázatba foglalva a hibaüzenetek, hibakódok, és az ilyenkori teendők. Ha nincs hiba, nem fog kelleni a táblázat, ha meg van hiba, úgy is megkeresi.

-fs-
Az olyan tárgyakat, amik képesek az mc futtatására, munkaeszköznek nevezzük.

Lehet, hogy mást értünk technikai dokumentáció alatt, de én doksit nem ebook olvasóval szoktam nézni, mert szvsz elég sok gond lenne vele. Hogy tudsz deeplinket küldeni másoknak egy konkrét fejezetre? Hogy oldod meg, hogy minden érintettnek a legfrissebb verzió legyen mindig az olvasóján? Stb.

Azért is parttalan és részben értelmetlen ez a beszélgetés mert nagyon sokféle technikai dokumentáció van, még ha egy dokumentációs kereten/szabványon belül nézzük is.

Természetesen van egy csomó féle szabvány és szokás is ezekre.

Mindegyik máshol húzza meg a határokat, máshogy fogják az emberek használni ergo más eszköz lesz alkalmas rá.

Én az egészből azt tartom a legfontosabbnak hogy hányan és hányszor olvassák. Pont nem érdekel milyen szép az a doksi ami a fióknak/devnullnak készül.

Gábriel Ákos

Hogy össze van zippelve :D

A konkrét tartalom az html5 és css*, maga az epub csak egy konténer, némi metadatával, toccal, több fileban lehet tartalommal megspékelve. Kb mind egy docx vagy odt, csak nyilván egy harmadik ugyanolyan, mert az a jó a szabványokban. Szóval publikációra hasznos, nem kell hozzá zinternet meg webserver.

*lehet benne egyébként hang, meg video, meg tök se tudja mi. Embedded audiobookot esetleg el tudok képzelni a gyakorlatban

( uid_6201 v | 2021. 02. 13., szo – 09:19 )

Szerkesztve: 2021. 02. 13., szo – 09:20

Érdekes köztes megoldás: LaTex az alap, de kényelmi saját szkriptekkel megsegítve.
Így az általad írt szöveg számodra kézenfekvő markdown-jellegű elemeket is tartalmazhat. Fordításkor az általad írt szkript pedig átdolgozza a jelölőnyelvi elemeket LaTeX szintaktikára és mehet rá a pdflatex, netán a lualatex.
Utóbbi képes implicit szkriptelésre, például lualatex általi fordításkor a tex fájlban levő LUA kóddal CSV-t felolvasva LaTeX táblázat varázslásra.

( muszike | 2021. 02. 13., szo – 17:55 )

Szerkesztve: 2021. 02. 14., v – 09:47

Markdown vagy Emacs Org lapok és valamilyen statikus site generátor? (Hugo)

( Aadaam v | 2021. 02. 13., szo – 20:31 )

Szerkesztve: 2021. 02. 13., szo – 20:39

Én abból élek hogy ilyeneket írok. Ha te választhatsz, akkor Confluence (jobb esetben Jira integrációval, esetleg egy jira RTM pluginnel), ha nem akkor van a Microsoft Word és a Microsoft Word.

van amúgy aki notion.so -ra esküszik, mi confluence.

A google docs alkalmatlanul primitív erre (been there done that many times), a Sharepoint meg összeb.ssza a szerkesztéseket (legalábbis 2020-ban 3, különböző negyedévben, különböző szervezeteknél, különböző technikával közösen szerkesztett Word doksi is szétb@szódott a közös szerkesztéstől, szóval as of writing ez egy elméleti ficsör, lehet azóta megy csak ha nem az sokmillió Forint, és kezdem unni.)

A markdown-t se képesek emberek megjegyezni, a latex pedig egy authoring tool, amit csak informatikusok fognak a kezükbe venni.

A nagyfiúk játéka az IBM Doors leszármazottak, kedvencem a Jama Connect, 14 millió a kezdőcsomag. Egyik projektben kifizettük, ez alapján továbbra is azt mondom, Jira+Confluence, mert a Jama-t se akarta érteni senki.

Az államigazgatás egyes bugyraiban szerkeszteni, kommentelni csak word-öt hajlandóak, ill. a közbesz pályázathoz is word-öt adnak ki, így ott nem játszik az, ami mindenhol máshol igen, hogy alapvetően Confluence, ez az amiben napi szinten dolgozunk és kidolgozzuk, meg kap linket a pályázó is, de az adminisztráció végett a teljig kiállításához kapnak egy PDF fájlt (meg ha rendesek vagyunk, egy Confluence space exportot, utóbbival kezdeni is lehet valamit)

A speckót ugyanis nem csak írni, olvasni is kell tudni, a Word magában pedig navigálhatatlan. Általában kell egy műszaki leírás (ami egy szöveg), meg egy követelményjegyzék (ami pedig tételes lista), és a kettőt integráltan kell tudni kezelni, ez azért a word + excel kombóban megcsinálva rengeteg idő.

Ezen kívül vannak a pontrakommentelős képernyő specifikálók mint a Zeplin.io meg a MarvelApp, de az egy külön sztori. EA licenszért szabályosan könyörgök hogy a beszállítónak legyen, de ma már lehetsz több cégnél is architect anélkül hogy beszélnél UML-ül, ami valahol ijesztő.

Hagyd a LaTeX-et a francba, az a speckó aminek a szerkesztéséhez is informatikai szakvizsga kell az esetek 99.9999%-ában sose valósul meg.

+1 , Confluence + JIRA páros teljesen használható. Confluence-nek a shared editing módja is elég jól működik, amikor többen szerkesztjük ugyanazt a doksit a'la Google Docs.

Ábrákhoz van draw.io plugin, kommunikációs célra egyszerűbb UML-eket is gyártottam már benne + persze színes dobozok és nyilak működnek dögivel, az UML-t úgyse érti senki...:)

Negatív példa: Van egy Miro nevű 2.5D -s zoomolható csoda (kicsit a Prezire hajaz élményben), amiben van sok jópofa feature, lehet benne mindenféle ábrát gyorsan összedobni, de utána nem lehet vele úgy továbblépni a megvalósítás felé mint egy Confluence + JIRA kombóval, szóval én inkább hanyagolnám.

( janoszen v | 2021. 02. 14., v – 15:26 )

Szerkesztve: 2021. 02. 14., v – 16:54

Asciidoctor vagy Markdown. Mi úgy oldodottuk meg, hogy minden modulnak saját readme-je (pl itt) van és abban van leírva a koncepció, valamint a publikus metódusoknak is van értelmes leírása. Ezen felül van egy fejlesztői doksi (mkdocs).

( _Franko_ v | 2021. 02. 15., h – 13:19 )

Mire kell?

Ha kilóra meg kell lennie valamennyi papírnak, akkor bármi jó, amit a menedzsment és/vagy a pályázat kiírója elfogad, ahhoz kell igazodni.

Ha értelmes célja van, vagyis horrible dictu dolgozni kell belőle, integrálódni, később hozzányúlni, akkor meg a projekt mellett a helye, szintén bármi jó, de a legjobb, ha a forráskóddal együtt lehet szerkeszteni, mert például refactor esetén az IDE szól, hogy van az adott dologról említés a doksiban, azon is változtatni kell.

A projekttől külön életciklust élő dolgok sajnos arra jók, hogy oda küldjük meghalni a dokumentumokat.

https://iotguru.cloud

Ebből kéne dolgoznia a fejlesztőnek.

legjobb, ha a forráskóddal együtt lehet szerkeszteni, mert például refactor esetén az IDE szól, hogy van az adott dologról említés a doksiban, azon is változtatni kell.

Melyik IDE tud ilyet?

Fejlesztéskor előbb a doksit módosítanánk, és ehhez kéne valami támogatás hogy könnyen látszódjon mit kell a doksi változás után húzni a kódban, nem fordítva.

A latexdiff nem az igazi, mert jelöli ugyan a változásokat szinezéssel meg áthúzással, de nem lehet végiglépkedni rajtuk, csak szemmel greppelve.

Meg lehet csinálni hogy txt alapú szövegszerkesztőben összehasonlítom a két verzióját a dokumentum forrásának és egyesével elfogadom a változásokat, de azért nem az igazi.

Melyik IDE tud ilyet?

IntelliJ biztosan, mert használtam már ilyenre, nyilván csodát nem kell várni, de átnevezéskor rákeres szövegfájlokban is.

Fejlesztéskor előbb a doksit módosítanánk, és ehhez kéne valami támogatás hogy könnyen látszódjon mit kell a doksi változás után húzni a kódban, nem fordítva.

Ha ott hever a doksi a forrás mellett és nem bináris fájl, hanem valamilyen markup, akkor ugyanúgy látszik a commit change, mint bármilyen forrásváltozás. Ha esetleg külön branch-en történik és ezzel nyílik a branch, plusz be van linkelve a ticket, ahol szintén le van írva a változás, az már igen kényelmes lenne, csak kérdés, hogy ki indítja a változást és ki tervezi meg, hogy mi változzon.

Azt kell eldönteni, hogy mire is kell a doksi és kik használják. Ha ez megvan, akkor tiszták lesznek az eszközök és a workflow.

https://iotguru.cloud

Hát ugye a jama (meg általában a Doors klónok, pl InnoSlate) a követelményeket számozott fejezetként kezelik.

ezeket a számozott fejezeteket lehet ticketként kezelni.

a jama hivatalos megoldása az az, hogy a követelmények forduljanak le EPIC-re jira-ba tasktop -pal, és amikor OK-ra jelölik a jira-ban az alá tartozó dolgokat akkor az is OK-ra jelölődik. 
 

https://youtu.be/ZkZDPVB28s0

De ha hagyod a jama-t a francba és jira RTM-et használsz, akkor ehhez integrálni se kell.

a jira ticketek kezelését meg megoldja az IDE az egyik oldalról (a másik oldalról meg pl justinmind-ban van jira integráció, ill. ha a szövegek nem jira-ban vannak hanem confluence-ben, azok is linkeltek, bár automatikusan nem szól ugye).

( Ritter | 2021. 02. 15., h – 21:12 )

Szerkesztve: 2021. 02. 16., k – 01:15

Doxygen

Természetesen érdemes hozzá a kódot is dokumentálva írni. Elég kényelmesen szép dokumentáció automatikus generálására képes. 

( khiraly | 2021. 02. 19., p – 16:46 )

Szerkesztve: 2021. 02. 19., p – 16:47

Nekem olyat ajanljatok, hogy tableten firkalok szoveget es abrat, es ezt szerverre szinkronizalom ugy, hogy a szoveg, szoveg, az abra pedig kep legyen, lehetoleg .svg-ben.

 

Mert most ugy van, hogy a laptopon .md-ben irok, ami a github flavor egy kicsit felpimpelve (tablazatnal ossze tud adni egy-egy oszlopot).

Minden lenyeges dolgot ebben irok fel. Viszont tableten sokkal kenyelmesebb 5letelni, rajzolni (abrat), amire a Samsung Notes programot hasznalom.

Ami a gyakorlatban ugy nez ki, hogy amit a tabletban irok, az ott is rohad meg. Max ha van erkezesem atviszem ujragepelve, a kepeket meg kifotozgatva a szgepre.

 

Nekem ez az atjarhatosag hianyzik. Jo lenne ha a tablet .svg-t csinalna, legjobb az lenne, hogyha .md-t, benne .svg-kel. Es akkor szerver oldalrol is hozza lehetne nyulni.

Saying a programming language is good because it works on all platforms is like saying anal sex is good because it works on all genders....

( bzs v | 2021. 02. 19., p – 18:41 )

Szerkesztve: 2021. 02. 19., p – 18:44

21 éve nem használok mswordot.

Javaslom ezt végigfutni:

http://www.bakoma-tex.com/doc/latex/siunitx/siunitx.pdf

ezzel elérheted könnyedén azt, hogy pillanatok alatt nyelvet váltasz, amikor mondjuk német után angolra fordítod az egészet.

Ábrákhoz a tikz csomagot javasolnám.

https://www.overleaf.com/learn/latex/LaTeX_Graphics_using_TikZ:_A_Tutor…

Szedőrendszert meg már ezek után meg sem kell említenem... :)

Az www.overleaf.com pedig megoldja, hogy online legyen az anyagod

10-féle lény van:
-- aki ismeri a bináris számrendszert,
-- és amelyik nem.