Jak pisać dobre poradniki - poradnik krok po kroku

Nieznajomy11 | 2019-01-03 13:53:06 UTC | #1

Witam,

To mój 1 poradnik na tym forum, lecz nie 1 w internecie

Przeczytałem ostatnio kilka poradnikow na forum i stwierdzam ze brakuje tutaj takiego poradnika

ktory by nauczyl pokazal innym jak sie pisze poradniki

Na poczatek, NIE PISZ TEGO W TEN SPOSÓB.

I. Prolog

Pisanie poradników niby prosta sprawa, bo jak wiemy pisać każdy może, trochę lepiej, lub trochę gorzej. Problemy osób piszących poradniki są często natury technicznej lub wynikają z braku umiejętności przyjęcia jakiejś spójnej budowy. Pisząc poradnik nie przekazujemy informacji mówiąc do kogoś, tylko przygotowujemy uporządkowaną instrukcję.

II. Budowa poradnika

Nie ma jednego sposobu tworzenia poradnika, niemniej trzeba pamiętać o uporządkowaniu i trzymaniu się wybranej metody na jego całości. Można by wymienić tutaj kilka podstawowych zasad:

Przede wszystkim pamiętajmy, że istnieje interpunkcja i polskie znaki, w dobrych poradnikach utrzymuje się poziom, to nie jest rozmowa z kolegą.
Zazwyczaj będziemy korzystać z grafik dodatkowo prezentujących kroki potrzebne do wykonania lub też ze wklejek kodu/komend gotowych do użycia. Każdy taki blok powinien mieć swój opis, zawsze umieszczony w ten sam sposób nad lub pod. Dodatkowo należy pamiętać, żeby kod/komendy umieszczać w przeznaczonym do tego znaczniku, który zostanie pokazany w części III.
Pamiętajmy o stosowaniu akapitów przy dłuższych fragmentach tekstu. Najlepiej to, jeśli w ogóle nie będziemy mieli potrzeby z nich korzystać poza głównymi sekcjami poradnika.
Ważne rzeczy w poradniku, a bardziej słowa kluczowe możemy pogrubić, jeśli będzie to ułatwiać czytanie (możliwość szybkiego odnalezienia w długim tekście czegoś, co nas interesuje). Wszystko jednak z umiarem i z tym też nie wolno przesadzać, bo osiągniemy odwrotny efekt.
Tytuł dobrego poradnika nie może zawierać zbędnych ozdobników oraz powinien być formułowany w sposób odpowiadający pytaniom zadawanym przez użytkowników:
Jak zrobić serwer Minecraft na VPS (trafiony)
Stawianie Spigota na VPS-ie (nietrafiony, niepopularna konstrukcja)
Instalacja Ubuntu 18.04 na VPS KVM (trafiony)
Ubuntu 18.04 i VPS KVM (nietrafiony, brak prostej informacji, o czym jest poradnik)
[INSTALACJA] Serwer FiveM [VPS] (nietrafiony, od takich oznaczeń są tagi oraz kategorie, phpbb jest już niemodne)
Instalacja serwera FiveM na VPS (trafiony, ładnie opisuje o czym będzie poradnik)
Instalacja PHP 7 na VPS z Ubuntu 14 (trafiony, gdy poradnik stosuje się tylko do ograniczonej grupy systemów)
Przyjmijmy, że każdy z poradników potrzebuje minimum trzech części (punkty oznaczone gwiazdką są sekcjami opcjonalnymi i są zależne od tworzonego poradnika):
Wstępu, w którym zawrzemy skrótowy opis poradnika: co osiągamy wykonując go, jakie są wymagania systemu oraz wymagania sprzętowe. Najlepsze poradniki mogłyby też określać czas potrzebny na wykonanie i ilość potrzebnych osób, ale nie przesadzajmy, to nie są meble z IKEA.
Właściwego poradnika, czyli sekcji, w której krok po kroku wytłumaczymy, co należy robić, aby uzyskać efekt opisany we wstępie. Pojedyncze kroki, gdy są bardziej niestandardowymi sytuacjami niż wpisanie komendy cd popieramy zrzutami ekranu (np. okno wpisywania hasła przy instalacji phpMyAdmin).
Zakończenia, czyli miejsca, w którym możemy podsumować poradnik oraz udzielić dodatkowych rad na temat tego, co właśnie powinno zostać osiągnięte. Umieszczamy tutaj też źródła, z których czerpaliśmy informacje, linki do dokumentacji oraz ewentualnych stron pomocy, jeśli dane oprogramowanie takie posiada (np. oficjalne forum wsparcia panelu gier).
*Rozwiązywanie problemów, czyli coś, co przydaje się, gdy opisujemy jakiś trudniejszy proces niż instalacja htop oraz używanie go. W tej sekcji zawieramy informacje, gdzie oprogramowanie zapisuje logi oraz (jeśli znane) wypisujemy lub linkujemy rozwiązania problemów (np. komunikat o braku rozszerzenia php_mysqli po instalacji phpmyadmina można rozwiązać najczęściej poprzez restart usługi apache2).

III. Strona techniczna, czyli markdown

Oto jest, drugi co do wielkości problem osób piszących poradniki. Czyli obsługa pozornie prostego, ale jak się okazuje, nie tak łatwego stylowania używając markdowna.

a) Podstawy formatowania tekstu

_kursywa_ lub *kursywa*

Wynik: kursywa lub kursywa

**pogrubienie**

Wynik: pogrubienie

b) Lista oraz tabela

```text
- listy
- wcale
- nie
- muszą
- być
- trudne

(Każde dwie spacje to kolejna sekcja)
```

Wynik:
- listy
- wcale
- nie
- muszą
- być
- trudne

text | 1a | 2a | 3a | |----|----|----| | 1b | 2b | 3b | | 1c | 2c | 3c |

Wynik:

1a	2a	3a
1b	2b	3b
1c	2c	3c

c) Cytaty

> tekst
który jest cytatem

> tekst
>
> z dłuższą przerwą
który jest cytatem

> cytat z z cytatem w
> > w środku

Wynik:

tekst
który jest cytatem

tekst

z dłuższą przerwą
który jest cytatem

cytat z cytatem

w środku

e) Kod

Wynik:

jakiś tekst ~~który nie zostanie sformatowany~~

Co by się stało jakby nie użyć ```:
jakiś tekst ~~który nie zostanie sformatowany~~

Wynik:

public Reply yey(String test) {
    return new Reply("w ten sposób pokolorujemy też nasz kod");
}
// fajne nie?

``~\~coś co nie chcemy aby zostało przetworzone, możemy tego używać do wbudowywania w tekście (np. komend) ponieważ nie jest blokiem~~``

Wynik:

~~coś co nie chcemy, aby zostało przetworzone, możemy tego używać do wbudowywania w tekście (np. komend), ponieważ nie jest blokiem~~

f) Separator

---

Wynik:

IV. Naucz mnie więcej

Jeśli chciałbyś nauczyć się więcej o markdown, zerknij tutaj. Pamiętaj jednak, że nie każdy markdown jest taki sam i w zależności od implementacji niektóre rzeczy mogą działać inaczej, lub może ich w ogóle nie być, bo wsparcie jest tylko częściowe. Do generowania tabelek przyda ci się to narzędzie.

V. Nadal nie umiem, to zbyt trudne

Jeśli ortografia nie jest twoją najmocniejszą stroną, to przypominam, że większość przeglądarek internetowych wyświetla niepoprawne (nieznane przeglądarce) słowa, możesz je wpisać w Google’a i sprawdzić czy cię on nie poprawi, przydatny może okazać się też internetowy słownik języka polskiego.

Zainteresuj się też narzędziem LanguageTool, które pomoże ci bardziej zautomatyzować pracę oraz rozwiązać większość problemów z interpunkcją i podobnych. Poza wersja www możesz korzystać też z rozszerzenia dla Mozilla Firefox lub Google Chrome.

Poradnik miesiąca: październik 2018

DoreK | 2018-10-15 20:26:29 UTC | #2

[quote=”Nieznajomy11, post:1, topic:8552”]
Zainteresuj się też narzędziem LanguageTool
[/quote]

Jest też inne narzędzie tego typu - https://www.ortograf.pl ;)

LinGruby | 2018-11-24 18:52:04 UTC | #3

Pozwolisz @Nieznajomy11 dodam uzupełnienie do Twojego poradnika w postaci .pdf z github’a

https://github.com/napcok/markdown/blob/master/poznaj_markdown.pdf

Jeszcze taka ciekawostka…

37|690x374

anon10657637 | 2018-11-26 16:31:24 UTC | #4

Ja od siebie dorzucę też narzędzie do tworzenia prezentacji w formie strony internetowej (tutaj: spięte z Jekyllem)
https://github.com/kacperduras/jekyll-remark