Vše co jste kdy chtěli říci o dokumentaci

manuals
documentation

#1

Snažíme se pracovat na zlepšování a rozšiřování naší dokumentace a rádi bychom si poslechli, co si o ní myslíte. Pokud máte nějaké komentáře ke konkrétnímu článku či manuálu nebo chcete přispět obecnějším komentářem, napište nám sem. Kromě toho velice oceňujeme i návrhy na konkrétní témata, která by vás zajímala. :bulb: :blue_heart:


Upgrade na Turris OS 3.9
OpenVPN certifikáty s heslem
Problémy po aktualizaci Turris 1.x na 3.8.2 // volná diskuze
#2

Předpokládám že Doplnění DNS/DHCP dokumentace je v hledáčku. Docela se na tyhle věci lidi ptali a i mě by to trochu zajímalo, konkrétně přidávání lokálních jmen bývá nejasné (*.lan, statické+dynamické, apod.)


#3

Já bych ocenil, kdyby bylo na první pohled jasné, jaký článek v dokumentaci je určen pro Turris 1.x, jaký pro Omnii a jaký je společný pro oba typy routerů.


#4

+1 primlouvam se za tenhle napad. :slight_smile:

A dale by se mi libilo pouzit v hlavnim menu/rozcestniku wrap_plugin jako je napr na strankach wiki.ubuntu. Vic grafiky a banneru v clancich pro prehlednost.

Nakonec bych take zacal uprednostnovat clanky v EN, kvuli sirsimu obecenstvu.


#5

Dokumentace je pro mě největší zklamání na celém projektu. Nejen, že se ta původní lepší jen minimálně, ale ani nové věci nejsou dokumentovány dobře. Chybí i články, jak řešit typické scénáře.

Předně bych oddělil návody pro Omnii a starší Turrisy. Pokud ne fyzicky, tak možnost filtrovat přes štítky “for Turris [1.0] [1.1] [Omnia]” + na hlavní stranu fotky všech tří zařízení s popiskem, aby lidi pochopili, že jsou 3 typy.

Potřeba dokumentace je pro mě paradoxně ještě větší od doby, kdy jste začali věci “zjednodušovat” přes Foris. Příklad:
Mám vyrobenou síť pro hosty. Po měsících se objevila tato možnost ve Forisu. Není však nikde popsáno, co to udělá na pozadí, jak se vytvořená rozhraní budou jmenovat (jestli to nebude kolidovat s tím co mám), jestli do té konfigurace lze manuálně zasahovat (např. měnit eth na kterém to visí), nebo jí to zase při příštím použití Forisu přepíše atd. Potřeboval bych do sítě pro hosty přiřadit kromě wifi ještě jednu LAN zásuvku. Přes Foris to přidat nejde a nějaká podrobná dokumentace, jak si to vše udělat ručně včetně firewallu atd asi nebude, protože síť pro hosty teď přece jde naklikat ve Forisu, tak na co to sepisovat. Mám ještě další VLAN na IoT (zařízení mohou jen na tu samou VLAN a router, ne ven) a bojím se na zkoušku aktivovat guest lan ve Forisu, aby mi to nějak to nastavení nedokopalo, nevím jaké všechny výchozí scénáře byly testovány - v dokumentaci nepopsáno, jestli testováno jen s továrním nastavením nebo i s několika jinými VLAN. A tak mám funkci ve Forisu nevyužitou a návody hledám všude možně.

Úplně stejně je to s VPN, potřeboval bych přístupové certifikáty s heslem, ve Forisu to nejde a návod není, VPN se přeci teď dá naklikat bez návodu - no tak jak chci nedá.

Tzn. zařazení těchto funkcí do Forisu vám možná pomyslně zaškrtlo “splněno”, jde se na další věc, ale pro mě to Forisové řešení je funkčně nedostatečné a nezdokumentované i nadále. Pokud by tu Foris nebyl, nutilo by vás to ty věci popsat, abychom si to uměli nastavit manuálně. Trochu se bojím, že to bude pokračovat, budou přibývat možnostmi omezené klikačky ve Forisu a ubývat (respektive nepřibývat) návody, jak to funguje a jak si to nastavit přesně podle svých potřeb.


#6

Když občas tady vidím některé otazky, tak se ptam, proč po dokončení wizardu nebo případně ve Forisu není odkaz na dokumentaci prostě bych tam viděl klidně i sekci Kontakt. Ale predtim bych to viděl na nejaky souhrn, na co se pustit hned po instalaci a případně způsoby, jak se bránit před SSH utokem. Tzn. Těch 5 důvodu, co se sepsalo v anglickém threadu.

Ale klidně podobný článek vytvořím, ale jde o to, aby to nebylo zbytečně i když… Říkám si (=> Myslím si), pokud to pomůže jednomu, tak to stojí za to úsilí.

Případně bych to viděl na nějaký checkbox ve Forisu na vypnutí/zapnuti nápovědy , kde by to bylo např. U Guest WiFi

Více se dozvíte v naší dokumentaci, kde je vysvětleno a podrobně popsáno k čemu se to hodí a co to udělá… (Když už je to tady nakousnuto)
Případně v dashboru měnit nápovědu např.
Víte, ze každý den na Vas může útočit? Podívejte se na clanek SSH Honeypotu, kde Vám poradíme jak a proč se bránit před útoky.

A např. si myslím, že by nebylo na škodu mít v dokumentaci pro Omnii:

  1. OpenMediaVault
    Jak nainstalovat a nastavit OpenMediaVault, ale když by to šlo naklikat rovnou přes Foris případně klidně vytvořit nějaký plugin do Forisu, jak je v případě BC, tak by to bylo ideální.
    Protože OMV běží na Debianu, tak bych uvítal, kdyby se dal ten kontejner automaticky aktualizovat (ne-li všechny) např. díky:
    https://www.cyberciti.biz/faq/how-to-update-debian-or-ubuntu-linux-containers-lxc/
    (byla by to další zajímavá feature pro Turris a hlavně při použítí samby,nfs v LXC by to bylo dost užitečné.)

  2. Plex/Emby (ale to zase záleží, zda by to nebylo lepší mít v Updateru)


#7

Odkaz na moji nedávnou prosbu už se tu objevil, nebudu se opakovat. Původně se sice týkal evergreenu DNS/DHCP, ale dovolím si zobecnit jej asi následovně:

  • Doplňte prosím jakousi “metadokumentaci”, kde by bylo jasně popsáno,

a) který konfigurační mechanismus je hlavní (/etc/config/*, tj. UCI?) a který je vedlejší (Foris, LUCi)?

b) jaký způsob konfigurace je podporován

c) co přesně znamená “podporován” (např. updater zachovává uživatelská nastavení, pluginy pro Foris pracují s uživatelskou konfigurací, zda jednosměrně či obousměrně, totéž pro LUCi)

  • Pokud to půjde, zkuste prosím psát dokumentaci v duchu

a) vstupní/omezující podmínky
b) stručné schéma/návod
c) seznam konfiguračních souborů (zdrojové->generované)
d) postupy při hledání chyb

Pokud bude dokumentace vycházet obecně z klasické konfigurace (/etc), je mnohem větší pravděpodobnost toho, že si uživatelé (třeba přes fórum) nějak poradí i při chybách v klikací nástavbě (a budou chápat její limity).


#8

Ještě bych sem s dovolením připsal jeden námět ke zlepšení dokumentace … a to její přehlednější roztřídění do tématických celků a v nich sdružit témata, která jsou víceméně o tom samém, jen jak projekt postupuje dále a rozšiřují se technologické možnosti routeru, lze to samé realizovat různými cestami (a samozřejmě i různě bezpečnými).

Dám příklad toho, co mám na mysli, aby to bylo pochopitelnější :slight_smile:

Tak například téma vzdáleného připojení do routeru z WAN sítě.
Historicky tu k tématu máme tři příspěvky:

  1. přístup z vnější sítě přímo přes protokol http (resp. https) nebo přes ssh
  2. přístup přes OpenVPN konfigurovaný manuálně
  3. přístup přes OpenVPN konfigurovaný klikáním ve Forisu

Téma by znělo "Vzdálený přístup k routeru z Internetu"
Odkazy do dokumentace by byly seřazeny podle bezpečnosti, tj. nejdříve 3) jako bezpečná a a na chyby nejméně náchylná varianta, pak 2) pro ty, co jim nestačí klikátko a vědí, co dělají, a nakonec 1) jako nejméně vhodný a nejméně bezpečný způsob realizace WAN přístupu k routeru.

A u dalších témat či okruhů tak nějak podobně.


Yes, I am leaving
#9

Když jsem psal “Chybí i články, jak řešit typické scénáře.”, tak jsem myslel něco podobného, ale obecněji. To není jen o přístupu k routeru, ale “domu” z WAN obecně. Trochu se mi ježí chlupy, když čtu, kolik lidí se ptá, jak otevřít port x+y+z a přesměrovat provoz na báječné čínské IP kamerky co jim míří do obýváku a koupili je super výhodně na Ali.
Mělo by se vysvětlit, že otevírat porty pro každou takovou jednotlivou krabičku je nesmysl, že tyto krabičky s pochybným, skoro vždy děravým, často kdoví co odesílajícím fw by vůbec neměly mít přístup do internetu, že by se to mělo řešit přes VPN a krabičky na VLAN bez přístupu ven, případně pokud jde o webserver a má být viděn, tak třeba LXC v DMZ. A z takového článku odkazy jak nastavit tu VLAN, VPN, DMZ, … Tj. ne aby člověk měl jen klikačku ve Forisu na VPN, ale aby věděl, proč je to lepší řešení a proč se nemá snažit vystrkovat ven všemožné porty atd. To by byl přínos CZ.NIC osvětě a bezpečnosti.
V současnosti sice je návod, jak udělat obecně VLAN, ale už není návod, jak nastavit fw pro různé účely té VLAN, např. pro ty IoT co nemají mít přístup ven. Teď tu jsou takové střípky, ale pokud chce někdo opravdu něco nastavit, musí shánět informace jinde.


#10

Zdravím,
Nevyznám se v tom, jak je nastavené logování, přes syslog a tak vůbec. Můžete sepsat jakou konfiguraci dodáváte a co to všechno dělá?

Rád bych si taky nějaké věci logoval, ale narazil jsem na to, že třeba konfig syslog.-ng není prázdný a nevím co s tím.

Děkuji.


#12

Plno věcí tam chybí, ne-konzistence mezi CZ / EN dokumentací


#13

Můžeš být, prosím, konkrétnější, co ti tam chybí?


#14

Řekl bych, že nic konkrétního nemá, jen měl z nějakého neznámého důvodu potřebu vytapetovat fórum.


#15

Videonávody jsou dobrá forma dokumentace … napadlo mne (po přečtení některých postů), ře by nebylo vůbec od věci udělat stručný rychlý videonávod na téma, jak vyměnit baterku na desce routeru.


#16

Něco takového? https://youtu.be/PW94kRfProE?t=35s


#17

Ano … jen v hlavní roli s naším routerem Turris a s komentářem od @Nora

P.S.: Mně také přišlo, že na tom nic složitého není a tu svou baterku v routeru už mám dávno vyměněnou, ale když si přečtete některé posty na tomto fóru (nic proti kolegům, kteří je napsali :-)), očividně to pro všechny snadný úkol není.


#18

@Nones Máte pravdu, nedávno jsem měnil baterie v ovladači od TV a přemýšlel jsem, že zavolám na podporu výrobci nebo IT technika… Nemohl jsem najít kde jsou uloženy. Po-té co jsem je našel tak nešli ven. Musel jsem to toho mlátit šroubovákem jako na videu. Při pohledu na Turris ani nevím jak se dostat dovnitř.


#19

Dobrý den,
uvítal bych aktualizaci návodu na instalaci LTE modemu. (již 3 měsíce mi Turris Omina leží na skříni a já jsem bez internetu)
https://doc.turris.cz/doc/cs/howto/lte_modem_install
Modem Quectel EC20 je podle informací co jsem se dočetl zastaralý, proto jsem si pořídil EC25. Ten ale s tímto návodem nefunguje. Jsem laik ale nějak mi tam chybí nějakej ovladač!?


#21

Jak bylo řečeno v dnešním příspěvku @cynerd v jiném postu, je tato sekce až na výjimky plná nekonstruktivních příspěvků a proto nemáme žádnou odpověď očekávat.

P.S. Moc tedy nechápu smysl tohoto postu, když se nejdříve team ptá a pak vlastně v plné namyšlenosti vyjde najevo, že je naše názory nezajímají.
Tedy možná zajímají, ale jen ty, co jim voní.

P.S.: Omlouvám se @Nora, že nejsem milý (jak mně bylo nedávno doporučeno), ale řídím se zásadou, jak Ty na mne, tak já na Tebe.


#22

Já všem děkuji za připomínky a návrhy, všechno jsem četla a průběžně se zamýšlíme jak a co integrovat. Budu se snažit to pomalu posouvat dál. V dohledné době bychom chtěli provést několik globálních vylepšení, nevnímejte to prosím jako to-do list, který bychom měli vytesaný do kamene v tomto kvartálu, ale jako nástin plánovaných změn:

  • zlepšení uspořádání článků do tématických celků a zpřehlednění hlavního menu
  • sidebar s navigací pro zlepšení orientace
  • nástroj pro reportování chyb/nepřesností (mělo by být možné označit přímo neuspokojivou část textu a navrhnout zlepšení)
  • tagování článků podle HW (Turris/Omnia/…)
  • lehké vykrášlení - výměna šablony

Co se týče konkrétních článků, které navrhujete, budu se k nim postupně vracet. Posílili jsme support tým a já bych tak měla mít více času na psaní a snad i na tvorbu videodokumentace. Souhlasím, že videonávody jsou mnohdy efektivnější, jsou ale také náročnější na vytvoření a je těžší je udržovat aktuální.