Dokumentacja produktu dla specjalistów WordPress

Opublikowany: 2017-07-28

Dokumentacja produktu jest zwykle postrzegana jako nieistotna, że można iść na skróty. Nie jest postrzegana jako coś, co może zaoferować klientowi wartość, ani jako coś, co mogłoby potencjalnie wpłynąć na kluczowe obszary biznesowe, takie jak przychody i marketing. To prawda, że jako specjalista od WordPressa nie będziesz musiał pisać dokumentacji w taki sam sposób, jak Atlassian czy Cisco. Zwykle, gdy ludzie myślą o „dokumentacji”, przywołują obrazy grubych, drukowanych instrukcji obsługi, indeksowanych alfabetycznie na bardzo dużej półce, której nikt nigdy nie czyta.

Ale to się zmieniło:

Wraz z pojawieniem się Agile i DevOps oprogramowanie do wysyłki stało się szybsze, a cykl rozwoju również stał się bardziej dynamiczny. W rezultacie dokumentacja odzwierciedla teraz obecny stan w najnowszym wydaniu, zamiast być czymś statycznym napisanym na papierze na zawsze. Dokumentacja jest zintegrowana z cyklem rozwoju i jest aktualizowana tak często, jak oprogramowanie.

Dlaczego profesjonaliści WordPress powinni dbać o dokumentację produktu?

Przydatna, aktualna dokumentacja nie tylko ułatwia życie użytkownikom, ale także dodaje poziom dopracowania, który staje się atutem marketingowym jak żaden inny. Z drugiej strony słaba dokumentacja ma negatywny wpływ. Prawdopodobnie sam tego doświadczyłeś: miałeś problem, na który usilnie starałeś się znaleźć rozwiązanie w dokumentacji, a kiedy nie, skończyłeś sfrustrowany (i prawdopodobnie zły). Pogarsza się tylko wtedy, gdy płacisz za produkt.

Jeśli pracujesz w agencji WordPress, dostarczanie dokumentacji we wszystkich obszarach projektu, od wstępnego projektu po zasoby, zwiększy poziom profesjonalizmu, pokazując, że:

Zwracasz uwagę na szczegóły.
Troszczysz się o swojego klienta na tyle, by pójść o krok dalej.
Jesteś przejrzysty i pewny swoich decyzji projektowych i technicznych.

Mike Puterbaugh, wiceprezes ds. marketingu w MindTouch napisał artykuł Mashable opisujący 5 powodów, dla których dokumentacja produktu stanowi atut marketingowy. Zakończył następującymi słowami:

Nie jest to seksowne przedsięwzięcie, ale zapewni ci szacunek rówieśników, skuteczniejsze zarządzanie firmą i bardziej współpracujący zespół. Bo nie chodzi o ten kwartał czy ten rok, ale raczej o wpływanie na przewagę konkurencyjną i długoterminowy wzrost.

Teraz, gdy mamy już wystarczającą motywację, będziemy:

Zapoznaj się z różnymi rodzajami dokumentacji produktów, które są istotne dla WordPress.
Omów potrzeby każdego typu dokumentacji i zaoferuj praktyczne porady.
Zaproponuj wstępne wskazówki dotyczące planowania i współpracy nad dokumentacją produktu. Zwłaszcza jeśli pracujesz w agencji WordPress.

Rodzaje dokumentacji produktu WordPress

Produkt WordPress to nie tylko wtyczki i motywy. W tej sekcji omówimy również pomoc online, interfejsy API REST i ciekawą rzecz zwaną mikrotreścią.

Wtyczki WordPress

Dokumentacja wtyczki WordPress musi zaspokoić dwie grupy: użytkowników i programistów. Potrzeby dokumentacji każdego z nich są inne, podobnie jak używany styl pisania.

Użytkownicy

Potrzeby użytkowników w zakresie dokumentacji dotyczą głównie rozwiązywania problemów i konfiguracji. Dodaj do tego, że musisz zaprezentować swoją wtyczkę w atrakcyjny sposób, aby użytkownicy mogli ją wypróbować. Każda wtyczka ma swoją własną stronę na rynku wtyczek WordPress. Pamiętaj o następujących kwestiach:

Napisz atrakcyjny i użyteczny opis, który zachęca do pobierania i używania.
Dodaj zrzuty ekranu z adnotacjami ze strony konfiguracji wtyczki Dashboard wraz z opisami.
Umieść pytania w FAQ, które są przydatne, a nie banalne.
Miej zaktualizowany i dobrze napisany Changelog. Nie dodawaj tam tajemniczych ani zwięzłych notatek.

Należy pamiętać, że użytkownicy korzystający z dokumentacji prawdopodobnie spieszą się i pragną znaleźć rozwiązanie. Pisz jasno, prosto i zwięźle. Nie utrudniaj im tego, niż jest.

Deweloperzy

Oprócz przestrzegania najlepszych praktyk oprogramowania i oficjalnych standardów kodowania PHP, powinieneś skupić się na następujących obszarach:

haki wtyczek

Wykonują one pracę polegającą na modyfikowaniu zachowania WordPressa. Całkiem prawdopodobnie twoja wtyczka WordPress ich używa. Ponieważ zaczepy wtyczek są ważną częścią kodu, powinieneś udokumentować, w jaki sposób ich używasz i w jakie funkcje WordPressa są zaangażowane.

tagi szablonu

Tagi szablonów to kolejny sposób na zwiększenie funkcjonalności wtyczki WordPress. Udokumentuj napisane przez siebie funkcje tagów szablonu. Dołącz przykłady, w jaki sposób inni użytkownicy lub programiści mogą używać tagów w swojej witrynie WordPress.

opcje

Opcje to sposób na przechowywanie określonych informacji w bazie danych WordPress. Odbywa się to za pomocą funkcji add_option i get_options. W takim przypadku udokumentuj parametry, które przekazujesz do tych funkcji.

Baza danych

Wtyczki często odczytują i zapisują wiele różnych rzeczy z bazy danych. Ponieważ są to podstawowe operacje, ich udokumentowanie znacznie pomoże innym programistom zrozumieć, jak działa Twoja wtyczka.

Motywy WordPress

Istnieją dwa różne obszary, w których można tworzyć dokumentację motywów. Pierwszy to pliki źródłowe. Komentowane pliki CSS są łatwiejsze do zrozumienia i odczytania niż te bez. Użyj narzędzia takiego jak css_doc, aby Ci pomóc. Generuje to dokumentację w stylu JavaDoc i można ją opublikować:

Drugi obszar to Przewodniki po stylu. Dokumenty te opisują, jak elementy muszą wyglądać i w jakich przypadkach należy ich użyć. Wymuszają spójność i ułatwiają współpracę. Możesz przeczytać 20 oszałamiających przykładów przewodników stylu marki Hubspot, ponieważ zawiera wiele świetnych przykładów.

Ponownie, nie zapomnij zapoznać się z oficjalnymi standardami kodowania CSS WordPress.

Tak szczegółowe udokumentowanie elementów projektu pomaga również w rekrutacji nowych pracowników, jeśli jesteś agencją WordPress. Przewodniki stylistyczne mogą być używane jako samouczki lub materiały referencyjne do pracy nowych i byłych klientów.

Pomoc online

Ponieważ pomoc online ma na celu rozwiązanie konkretnego problemu użytkownika, należy zacząć od listy typowych zadań i problemów. Chociaż na początku lista nie będzie wyczerpująca, poświęć trochę czasu na wyprodukowanie jak największej liczby konkretnych przedmiotów. Pomysł polega na napisaniu pliku pomocy online dla każdego z tych zadań i problemów oraz hiperłączu do powiązanych informacji. Możesz tworzyć podróże użytkowników, aby odwzorować różne ścieżki, które użytkownik może obrać i wykonać w Twojej aplikacji. Zagłębienie się w e-maile pomocy technicznej, aby zauważyć często zadawane pytania i problematyczne obszary, to dobry sposób na aktualizowanie i aktualizowanie bazy wiedzy.

Barry J. Rosenberg, autor Spring into Technical Writing, oferuje następujące porady dotyczące pisania dobrych plików pomocy:

Każdy plik pomocy powinien być jak najkrótszy. Preferuj listy numerowane od wypunktowanych. Nie dygresj, nie rób przypisów i nie chciej. Skoncentruj każdy plik pomocy na pojedynczym zadaniu.

Mikrotreść

Mikrotreść ma dwie definicje: pierwsza to treść, taka jak nagłówki i sekcje, które użytkownicy przeglądają, aby uzyskać sedno konkretnego artykułu. Drugi to małe fragmenty treści, które mogą stać samodzielnie i są wykorzystywane do poprawy komfortu użytkownika. Jednym z doskonałych przykładów, jakie mamy na myśli, jest fragment „kilka osób pisze na maszynie” Slacka. (choć Slack jest pełen świetnie napisanych mikrotreści).

Ten bit jest wyzwalany, gdy więcej niż 3 osoby jednocześnie piszą na tym samym kanale. Zamiast po prostu drukować listę osób, które obecnie piszą, Slack bierze tę nudną informację i dodaje do niej trochę zabawy. Dyskusja robi się naprawdę gorąca i to widać. Jest to doskonały przykład tego, jak dokumentacja produktu (wiadomości aplikacji są tego częścią, nie?) sprawia, że ludzie o tobie mówią (i tworzą zabawne memy, takie jak powyższe).

REST API

Dokumentowanie interfejsów API REST jest osobną sztuką samą w sobie. Podobnie jak w przypadku każdego pisma technicznego, powinieneś dążyć do zwięzłości, jasności i prostoty definicji. Ponieważ interfejsy API REST mają swój własny format i zawiłości, nie można zrobić nic gorszego niż zapoznanie się z doskonałym przewodnikiem dotyczącym dokumentowania interfejsów API autorstwa Toma Johnsona na jego blogu I'd Rather Be Writing.

Współpraca i planowanie dokumentacji

Docelowo dokumentacja powinna być częścią projektu produktu. W związku z tym powinieneś podejść do tego jako do dodatkowego potoku w swoim cyklu oprogramowania. Oznacza to używanie repozytoriów oprogramowania do przechowywania najbardziej aktualnej wersji dokumentacji, używanie narzędzi do śledzenia błędów/problemów do monitorowania zadań i problemów, uwzględnianie planowania projektów dokumentacji w planie działania oraz, co nie mniej ważne, współpracę z innymi ludźmi. Ogólny zarys tego, jak zacząć, może być następujący:

Zapisz wszystko , co użytkownik chciałby wiedzieć, a także obszary, do których będziesz musiał napisać tekst.
Gdy już masz wszystko, pogrupuj je w kategorie i stwórz tytuły dokumentów.
Napisz specyfikację dla każdego dokumentu, wyszczególniając takie rzeczy, jak tytuł, opis, grupa docelowa, media (jaką formę będzie miał dokument), długość, ile czasu zajmie itp.
Dodaj szacunki ze specyfikacji dokumentacji do planowania projektu.

Ponieważ dokumentacja produktu obejmuje wszystkie obszary, jest prawie pewne, że będziesz musiał pracować z różnymi osobami w organizacji. Dobrym pomysłem jest usiąść i uzgodnić jakiś proces, jak to wszystko pójdzie. Jak w każdym projekcie, należy wskazać interesariuszy, którzy zapewnią pomoc techniczną, a także tych, którzy będą przeglądać i edytować zmiany.

Powinny być różne etapy procesu. Powinny one określać, gdzie gromadzone są informacje, kiedy dokument jest pisany, kiedy jest gotowy do korekty literackiej, na uwagi techniczne, publikację i tym podobne. Podkreśl różnicę między komentarzami literackimi, technicznymi i merytorycznymi. Na przykład nie jest to naprawdę przydatne, gdy poprosisz lidera zespołu o skomentowanie twojego dokumentu i zamiast informacji związanych technicznie, otrzymujesz wołanie o gramatykę i interpunkcję.

Zamknięcie

Dokumentacja produktowa to atut, który procentuje w dłuższej perspektywie. Daje wartość Twojemu klientowi. Może być nawet tak dobry, jak na przykład dokumentacja API Stripe, że ludzie zachwycają się tym na forach. To buduje zaangażowanie i reklamuje Twoją markę i produkt w naturalny i skuteczny sposób. W połączeniu z kreatywnymi mikrotreściami osiąga to, co miał na myśli Mike Puterbaugh, kiedy mówi, że dokumentacja produktu jest „tajną bronią marketingu”.