Jak czytać i pisać dokumentację oprogramowania
Marcin Sędłak-Jakubowski
Hejka
1. Nauczyciel angielskiego
... Bylejaki Pythonista
2. Technical writer
Po co mi dokumentacja?
By móc użyć swojego kodu 6 miesięcy później
By inni używali twojego kodu
By inni pomagali ulepszyć twój kod
Rodzaje dokumentacji
1. Tutorial
- Zorientowany na naukę
- Jest rodzajem lekcji
- Analogia: uczenie dziecka gotować
2. How-to guide
- Zorientowany na cel
- Pokazuje jak rozwiązać problem
- Jest zestawem kroków
- Analogia: przepis w książce kucharskiej
3. Wyjaśnienie
- Zorientowane na zrozumienie
- Wyjaśnia
- Opisuje kontekst i tło
- Analogia: artykuł o społecznym aspekcie gotowania
4. Technical reference
- Zorientowane na informacje
- Opisuje działanie
- Jest szczegółowe i konkretne
- Analogia: artykuł encyklopedyczny
| Dobre kiedy się uczymy | Dobre kiedy pracujemy | |
| Praktyczne kroki | Tutorial | How-to guide |
| Wiedza teoretyczna | Wyjaśnienie | Reference |
Jak czytać dokumentację?
Scenariusz 1:
Wstępne rozeznanie
man pgrepScenariusz 2:
Szybki start
Scenariusz 3:
Pomocy, utknąłem!
Cechy dobrej dokumentacji
Ma być
Ma być poprawna
Architektura informacji
Every page is page one
Plan
Pisanie
Redakcja
Działające przykłady
Żarty na bok
Na ratunek: mikrohumor
Jak tworzyć dokumentację?
Zacznij od README
Style guide
Style Guide
- Zbiór decyzji językowych
- Wybierz jeden i trzymaj się go
- Stwórz własny
- Np. Microsoft Style Guide
Narzędzia
HTML, XML
np. MadCap Flare
Online
np. Atlassian Confluence
Prosty markup
Markdown / reStructuredText
Static Site Generators
Docs-as-Code
Dokumentacja jak kod
- Issue trackers
- Version control (Git)
- Plain text markup (Markdown, reStructuredText, Asciidoc)
- Code reviews
- Automated tests
Co robię jako technical writer
Szczęśliwi użytkownicy
Chcę dorzucić cegiełkę do open source
Dokumentacja!
Linki na koniec
Jak czytać i pisać dokumentację oprogramowania
Marcin Sędłak-Jakubowski