/manuals/how-i-write-manuals-here
Jak piszę tutaj instrukcje (szablon i ściąga)
Struktura, której używam w każdej instrukcji na tej stronie, plus krótka ściąga z bloków kodu, wyróżnień i tabel.
- meta
- astro
To jednocześnie pierwsza instrukcja na tej stronie i szablon dla wszystkich kolejnych. Każda instrukcja ma tu mniej więcej ten sam kształt: jaki problem rozwiązuje, co trzeba mieć przed startem, kroki oraz pułapki, na które natrafiłem po drodze.
Co będzie potrzebne
- Problem wart udokumentowania
- Polecenia albo kliknięcia, które faktycznie zadziałały
- Pięć minut, żeby to zapisać, zanim się zapomni
Kroki
1. Określ cel
Jedno albo dwa zdania: co po zakończeniu będzie działać, a wcześniej nie działało.
2. Pokaż polecenia
Zawsze zaznacz, o jaką powłokę lub narzędzie chodzi:
# Połączenie z Microsoft Graph z potrzebnymi uprawnieniami
Connect-MgGraph -Scopes "DeviceManagementManagedDevices.Read.All"
Get-MgDeviceManagementManagedDevice -Top 10# Linuksowy odpowiednik "a próbowałeś wyłączyć i włączyć?"
systemctl restart the-thing.service
journalctl -u the-thing.service -f3. Wypunktuj pułapki
Uwaga! Tak wygląda wyróżnienie — używam go do kroku, który wszyscy robią źle za pierwszym razem.
Jest też zwykły wariant na informacje przydatne, ale nieszkodliwe.
4. Podsumuj ustawienia
Tabele dobrze sprawdzają się jako ściąga z konfiguracji:
| Ustawienie | Wartość | Dlaczego |
|---|---|---|
| Przypisanie | Wymagane | Użytkownicy zapominają o opcjonalnych |
| Czas na restart | 120 min | Żeby zdążyć w przerwie obiadowej |
| Zakres | Grupa pilotaż. | Testuj na ludziach, którzy wybaczą |
Rozwiązywanie problemów
Na końcu opisz błędy, które faktycznie zobaczyłeś, i to, co je naprawiło. To ta część, na której najbardziej zależy wyszukiwarkom — i zdesperowanym adminom o drugiej w nocy.