Přispějte do Krátkých dokumentů

Dokumentační tým Fedory. Verze all versions Last review: 2023-08-25
Cílem je přepracování wiki stránek - kde se užitečné návody mísí s návrhy dokumentace, interními poznámkami - do pěkných, tématicky orientovaných návodů "jak na to" a tutoriálů s ukázkami kódu, s pracovním tokem založeným na pull-requestech. Uvítáme vaši pomoc!

Kroky

  1. Zvolte si dokument, který chcete aktualizovat. Dokumenty s potřebou aktualizace lze nalézt v souboru modules/ROOT/nav.adoc. Nalézají se na zakomentovaném řádku (začínají textem //FIXME).

  2. Forkněte repozitář https://pagure.io/fedora-docs/quick-docs.

  3. Proveďte úpravy souboru s příponou .adoc, který chcete vylepšit.

  4. Odstraňte zakomentování souboru v nav.adoc, odstraňte slovo FIXME z xref.

  5. Sestavte si místní náhled (local preview), abyste zjistili, že změny odpovídají vašemu záměru. Ujistěte se, že máte nainstalován Podman nebo Docker. Na Linuxovém desktopu spusťte ./docsbuilder.sh. Na macOS spusťte ./docsbuilder.sh -p nebo ./preview.sh. Postupujte dle pokynů zobrazené na obrazovce (příkazovém řádku).

  6. Jste-li spokojeni se svými úpravami, vytvořte pull request.

  7. Při migrování wiki stránky, na staré stránce (wiki) vytvořte přesměrování — viz níže.

Možný zdrojový materiál

Možná, že chcete jen vylepšit existující dokument, v tom případě si vystačíte s tím, co je uvedeno výše. Nebo snad již máte něco ve své mysli. Ale pokud máte zájem pomoci, avšak nevíte kde začít, zde jsou některá místa, na která se lze podívat pro inspiraci:

  • Dřívější How To kategorie na wiki stránkách Fedory. Mnoho z těchto dokumentů je zralých na konverzi. (Mnoho z nich je také neaktuálních!)

  • Dotazy Obvyklých problémů na Zeptejte se Fedory.

  • Časté dotazy o Fedoře na Stack Exchange.

  • Fedora Magazine články. Formát magazínu je konverzační a chápán jako představující daný okamžik v čase. Verze v Krátkých dokumentech by měly být zaměřenější na danou problematiku a udržované aktuální, pokud se příkazy nebo nejlepší praxe změní.

Přesměrování wiki stránky

Wiki stránky obvykle neumožňují přesměrování na externí webové stránky, neboť potenciál pro zneužití je velmi vysoký. Pro Fedora Wiki jsme vyvinuli zásuvný modul, který povoluje přesměrování pouze na tyto stránky (Fedora Docs). Přesměrování lze vytvořit za pomoci makra #fedoradocs a vložením do vrchní části wiki stránky, kterou chcete nahradit, zhruba následujícího:

{{#fedoradocs: https://docs.fedoraproject.org/en-US/council/fpl/}}

Samozřejmě měli byste nahradit vzorové URL tím, které představuje vaši novou cílovou stránku. URL opět nemůže být cokoliv, musí začínat s https://docs.fedoraproject.org/.

Pokud je přesměrování zprovozněno, návštěvníci dané wiki stránky budou již pokaždé přehozeni (tedy přesměrováni s kódem 301 Moved Permanently) na dokumentační webové stránky.

Uvědomte si, že není prováděna žádná validace, že cílová stránka (odkaz) existuje nebo je správný — prosíme, překontrolujte si, že jakékoliv přesměrování, které vytváříte, funguje bezchybně před pokračováním dále.

Potřebujete-li upravit wiki stránku, abyste opravili URL, nebo odstranili z nějakého důvodu přesměrování, vytvořte URL wiki stránky s &action=edit, na příklad:

https://fedoraproject.org/w/index.php?title=Project_Leader&action=edit

Want to help? Learn how to contribute to Fedora Docs ›