Dokumentowanie wtyczek i motywów WordPress

Opublikowany: 2017-03-17

Dokumentacja jest zwykle doceniana tylko wtedy, gdy pojawia się problem i potrzebujesz szybko odpowiedzi. W tym artykule omówimy powody, dla których pisanie dokumentacji zasobów WordPress jest ważne dla Twojej praktyki jako programisty WordPress oraz jakość dostarczanych motywów i wtyczek.

Dlaczego dokumentacja jest ważna?

Prowadzenie aktualnego zestawu dokumentacji dotyczącej Twoich projektów, zasobów lub produktów jest ważne z wielu powodów.

Po pierwsze, jest to powszechne doświadczenie, gdy patrzysz na coś, co zrobiłeś 2 miesiące temu i od tego czasu nie dotykałeś, i nie masz pojęcia, co to oznacza. Kiedy ją rozwijasz, masz to wszystko w swojej głowie, ale tego zrozumienia nie będzie w przyszłości. Tak więc albo używanie komentarzy w kodzie wbudowanym, albo pisanie notatek w postaci zwykłego tekstu w Markdown, znacznie pomaga uchronić przyszłe ja przed zamieszaniem.

Po drugie, dokumentowanie zasobów jest przydatne dla innych programistów WordPress. I to ma sens, nawet jeśli jesteś samotnym freelancerem (w pewnym momencie będziesz musiał współpracować z innymi ludźmi). Będą musieli użyć tych zasobów lub zostaną poproszeni o ich utrzymanie i/lub aktualizację. Bardzo frustrujące jest używanie nieudokumentowanego kodu, który został napisany przez kogoś, kogo nie ma w pobliżu, aby zapewnić wsparcie lub wyjaśnić niektóre trudne fragmenty.

Wreszcie, dokumentacja dodaje, że Twoje produkty wyglądają na „dopracowany”, a Twoi klienci będą Cię bardziej kochać.

5 zasad efektywnej dokumentacji

Pisanie techniczne jest dyscypliną samą w sobie i służy do przekazywania informacji technicznych w jasny i jednoznaczny sposób. (Nie tylko komputery, na przykład prawnicy i lekarze posługują się również własnym językiem technicznym). Z tego powodu dokument, który jest uważany za pismo techniczne, zwykle ma określony styl i jest zgodny z zestawem zasad.

Przejdźmy przez 5 najważniejszych, abyś mógł napisać skuteczną dokumentację swoich produktów!

Wolisz używać mniej słów niż normalnie używasz w swoim piśmie: Każde słowo powinno mieć cel. Bądź bezpośredni i prosty. Dokumentacja jest zwykle poszukiwana, gdy dana osoba ma kłopoty i chce szybko znaleźć rozwiązanie. Na przykład zdanie takie jak „Niepowodzenie zniszczenia obiektu Q spowoduje wycieki pamięci” jest lepsze niż „Niepowodzenie zniszczenia obiektu Q spowoduje wprowadzenie wycieków pamięci”.
Wolę używać głosu aktywnego zamiast biernego: „ Kliknij przycisk w prawym górnym rogu” zamiast „ Należy kliknąć przycisk w prawym górnym rogu”. Używanie aktywnego głosu usuwa wszelkie niejasności dotyczące tego, kto co robi. Głos pasywny jest używany tylko wtedy, gdy musisz skupić się na obiekcie, a nie na przedmiocie (na przykład Platforma Pressidium jest zbudowana z myślą o bezpieczeństwie ) .
Używaj języka opisowego, gdy musisz opisać pojęcia, i imperatywnego, gdy musisz opisać procedurę krok po kroku (np. samouczki).
Użyj list wypunktowanych, gdy chcesz wymienić rzeczy, które nie mają kolejności, i list numerowanych, gdy kolejność punktów jest znacząca.
Upewnij się, że sam przetestowałeś instrukcje przed ich przedstawieniem!

Dokumentowanie wtyczek WordPress

Wtyczki WordPress są jak każde inne oprogramowanie. Zapewniają określoną funkcjonalność, wymagają instalacji, a czasem także rozwiązywania problemów. Bez względu na to, jak proste są, zawsze dobrym pomysłem jest dostarczenie odpowiedniej ilości dokumentacji, ponieważ nie wszyscy użytkownicy mają taką samą wiedzę techniczną.

Opublikowanie wtyczki WordPress na wordpress.org zapewni Ci miejsce na umieszczenie instrukcji instalacji, zrzutów ekranu, FAQ, a nawet Changelog! Wypełnianie ich przydatnymi i jakościowymi informacjami jest kluczem do zwiększenia popularności Twojej wtyczki:

Napisz atrakcyjny i użyteczny opis, który ostatecznie sprawi, że użytkownik pobierze Twoją wtyczkę i odwiedzi Twoją witrynę.
Dodaj zrzuty ekranu z adnotacjami wyjaśniające każdy element konfiguracji Twojej wtyczki, dodatkowo do tych pokazujących, jak Twoja wtyczka wygląda w przeglądarce.
Umieść pytania w FAQ, które nie są banalne. Dobrym sposobem na odkrycie dziwnych skrajnych przypadków jest poproszenie znajomego, który nie zna się na komputerach, aby użył Twojej wtyczki.
Miej zaktualizowany i dobrze napisany Changelog. Lapidarne i zagadkowe teksty są wielkim nie-nie i pokazują, że tak naprawdę nie dbasz o swoich użytkowników.
Upewnij się, że kod wtyczki jest dobrze skomentowany i zgodny z najlepszymi praktykami oprogramowania i oficjalnymi standardami kodowania.

Jeśli utkniesz i potrzebujesz inspiracji, przeprowadź małe badanie i zobacz, jak tekst jest napisany w popularnych wtyczkach, które mają setki tysięcy instalacji, w porównaniu z mniej używanymi.

Dokumentowanie motywów WordPress

Dokumentowanie motywów WordPress to zupełnie inna sprawa. Najczęstszym problemem z motywami WordPress jest brak wiedzy, która sekcja odpowiada jakiemu elementowi wizualnemu. Nie wszyscy biegle posługują się CSS:

Utwórz hierarchię wszystkich sekcji swojego CSS wraz z odpowiadającymi im opisami.
Do każdej sekcji dodaj zrzut ekranu z adnotacjami, szczegółowo opisujący każdą funkcję, wraz z małym przykładem. Nie zapomnij używać głosu aktywnego i języka rozkazującego, gdy pokazujesz, jak zrobić coś, co wymaga od użytkownika postępowania zgodnie z instrukcjami.
Użyj narzędzia takiego jak css_doc, aby Ci pomóc. To generuje dokumentację w stylu JavaDoc i może być opublikowana.
Czasami komentarze w kodzie nie wystarczą i trzeba utworzyć dokument Przewodnika po stylach dla motywu CSS. Dokumenty przewodnika po stylu opisują, jak elementy powinny wyglądać i w jakich przypadkach należy ich użyć. Wymuszają spójność i ułatwiają współpracę. Zobacz ten przykład przez Google.
Użyj struktury CSS, takiej jak Blueprint CSS. Pomoże Ci to w rozwoju, zapewniając zestaw narzędzi, takich jak dostosowywalna siatka, domyślna typografia, która działa, resetowanie CSS przeglądarki i wiele innych.
Ponownie, nie zapomnij zapoznać się z oficjalnymi standardami kodowania CSS WordPress.