Ta strona zawiera szczegóły projektu technicznego do pisania w sezonie Dokumentów Google.
Podsumowanie projektu
- Organizacja open source
- WordPress
- Pisarz techniczny:
- taktyka
- Nazwa projektu:
- Pełny i odświeżony zestaw poradnika stylu dokumentacji
- Długość projektu:
- Długotrwałe (5 miesięcy)
Opis projektu
Streszczenie:
WordPress to globalna organizacja non-profit zajmująca się oprogramowaniem, której celem jest pomaganie społecznościom globalnym za pomocą oprogramowania podkreślającego dostępność, wydajność, bezpieczeństwo i łatwość użytkowania. Celem WordPressa jest upowszechnianie demokratyzacji oprogramowania wydawcy i oprogramowania typu open source w internecie. W naszej epoce cyfrowej witryna jest dosłownie internetową fasadą organizacji lub osoby. WordPress wykonuje ogromne zadanie polegające na wydajnym obsłudze setek milionów użytkowników – odpowiada za 35% internetu – za pomocą swojego oprogramowania. Aby zapewnić im jeszcze większą efektywność, udostępniamy dokumentację, która jest niezbędna dla większości deweloperów, administratorów i użytkowników końcowych. W związku z tym dokumentacja może stać się podstawowym czynnikiem ekosystemu WordPressa. Obecna dokumentacja WordPress nie zawiera uniwersalnego i ujednoliconego zestawu reguł i wytycznych dotyczących stylu publikowania. Celem tej propozycji jest stworzenie pełnego, odnowionego zestawu wytycznych dotyczących stylu dokumentacji, które będą uniwersalnie stosowane w dokumentacji WordPressa. Projekt obejmuje ujednolicenie wszystkich aspektów wytycznych dotyczących stylu i projektu, takich jak semantyka, składnia, wytyczne gramatyczne, interpunkcja, reguły dotyczące programowania, atrybuty projektu i szczegóły formatowania. Obejmuje ona też konwencje językowe, takie jak głos, ton, czas, wszystkie części mowy oraz konwencje nazewnicze. Narzędzia, języki i platformy to WordPress CMS, GitHub i Markdown. Mogą się też składać z języków PHP/MySQL, HTML/CSS i JavaScript.
Plan projektu:
Obecny stan przewodników po stylu dokumentacji WordPressa: Zespół dokumentacji WordPressa wdrożył niezadeklarowaną, ale jednomyślną metodologię publikowania wytycznych. Jednak raz na jakiś czas pewne elementy są przypuszczone, a proces ten staje się spekulacyjny. Nie ma stałego standardu ani kryteriów dotyczących pisania i publikowania artykułów w WordPress. Zespół dokumentacji opracował wytyczne dotyczące stylu, ale nie ma takich, które byłyby uniwersalne. Większość istniejących wytycznych dotyczących stylu nie jest zebrana w jednym podręczniku lub jest wycofana i wymaga aktualizacji. Dlatego trzeba opracować i opublikować ujednolicony przewodnik po stylu, aby ujednolicić dokumentację WordPressa.
Cele:
Ponad 35% witryn w internecie działa na WordPressie, co oznacza, że miliony programistów i użytkowników końcowych korzystają z jego imponujących funkcji. Dokumentacja jest niezbędnym elementem, który pomaga deweloperom i użytkownikom skutecznie korzystać z tych funkcji bez żadnych problemów, nawet w razie niedogodności. Ogólnym celem tej propozycji projektu jest ustandaryzowanie poradnika projektowania i stylizacji, ujednolicenie istniejących przewodników stylistycznych i ich aktualizacja, a także dołączenie nowych przepisów i specyfikacji do dokumentacji WordPressa. Umożliwiłoby to łatwość użycia, prostotę i jednolitość dokumentacji WordPress.
Wdrożenie:
Jak sugeruje mentor (Jon Ang), projekt można podzielić na 4 etapy: odkrywanie, definiowanie, wdrażanie i konserwacja. Przed rozpoczęciem projektu, w okresie przedstawowym, będę współpracować z mentorem i opracowywać odpowiedni harmonogram oraz harmonogram realizacji kolejnych zadań i produktów. Zapoznam się bliżej z systemem WordPress i protokołami pracy w ramach tego projektu.
Na początku stażu omówię z mentorem i opublikuję streszczenie planu. Ustala się wymagania i potrzeby. Najpierw opiszę proces dokumentacji i interakcji z użytkownikiem. Następnie zostaną przedstawione wireframe układu każdej sekcji, kategorii i elementu. Układy te zostaną sprawdzone przez mojego mentora. W razie potrzeby układy zostaną przeprojektowane, a niektóre komponenty dodane lub usunięte. Następnie przeprowadzę badania użytkowników, aby określić użyteczność i możliwość zastosowania ścieżki interfejsu. Następnie w każdej sekcji zostanie zastosowany styl z poradnika dotyczącego stylu dokumentacji (jak pokazano na diagramie poniżej). Do naszego przewodnika można dołączyć odniesienia do przewodników innych organizacji, które są objęte licencją open source lub licencją Creative Commons. Jeśli w tym czasie wystąpią jakieś problemy z użytecznością, zmienię ich wygląd.
Testowanie i optymalizacje będą przeprowadzane po skończeniu poradnika stylistycznego i zintegrowaniu go z HelpHub. Wszelkie luki w zabezpieczeniach, zbędne elementy lub komponenty zostaną usunięte. Przeprowadzimy testy interfejsu użytkownika i kodu oraz w razie potrzeby poprawimy niechciane błędy. Ostateczna kontrola jakości całego przewodnika stylistycznego zostanie przeprowadzona pod kątem języka, gramatyki, pisowni, interpunkcji itd.
Zadania oczekujące z powodu nieprzewidzianych opóźnień zostaną ukończone w okresie buforowym. Dodatkowe funkcje, które zostaną uznane za możliwe do realizacji w trakcie projektu, można wdrożyć po zakończeniu testów końcowych. Nastąpi utworzenie planu wdrożenia, a gotowy produkt zostanie przesłany.
Narzędzia i metody:
Dokumentacja zostanie skompilowana i edytowana na platformie współpracy, takiej jak Dokumenty Google. Jeśli wymaga tego publikowanie w GitHub, można też zastosować języki znaczników, takie jak Markdown lub GitHub Flavored Markdown. W przypadku standardów projektowania i stylu można też odwoływać się do wytycznych dotyczących stylów open source. Na koniec gotowy dokument zostaje sformatowany i opublikowany w WordPressie.
Tabela komponentów:
Poniżej znajduje się pełna lista komponentów, które można zaimplementować w przewodniku po stylach. Wytyczne dotyczące dokumentów – dostępność, struktura dokumentu, kodowanie, źródła zewnętrzne, fakty, czcionki, odbiorcy na całym świecie, inkluzywne podejście, legalność, dostępność na wielu platformach, jednoznaczność, brak nadmiernych roszczeń, układ strony, poprawność polityczna, protokoły, bezpieczeństwo, struktura zdania, zwięzłe pisanie, ton i styl, bezstronność
Język i gramatyka – skróty i akronimy, afirmacje i negacje, artykuły, wielkie litery, klauzule, mowa bezpośrednia/pośrednia, pierwsza/druga/trzecia osoba, płcie, glosariusz, rzeczowniki, prefiksy i sufiksy, przyimki, zaimki, odwołania, terminy i żargon, tenbon, tenbon, ortograficzny, techniczny
Interpunkcja – apostrofy i cudzysłowy, dwukropki i półkolony, przecinki, wielokropki, wykrzykniki, łączniki i myślniki, nawiasy, kropki, znaki zapytania, ukośniki
Formatowanie - pozostałych - krenie - Abstracts, , Introduction, The Introduction, The Art. Inquis, Prefaces, The Art. The Art. The Art. Art. The Art. Mark Names, Brand Names; Nazwa Klienta. Nazwa produktu, Podpisy, Fragmenty kodu, Fragmenty Kodów Kodów Kodów; Kod; Data i godzina; Strefa czasowa. Miejsca. Miejsca, Miejsca; Wybrane.,;;”. Elementy, ani Państwa strefy. Tę. Państwa strefy czasowe; Miejsca. poznać jego datę i godzinę; Państwa strefy czasowe; Miejsca. Miejsca, Mik. Państwa nazwy i nazwy plików. Strony. Kody stref czasowych; Miejsca; Miejsca; Miejsca; Wybrane.,;;; Nazwa pliku; Strony strefy czasowej; . Miejsca. Miejsca, Wal., ; Nazwa pliku; Nazwa pliku; Strony ze strefy czasowej; . Miejsca, Miejsca, Mik., nazwy plików; Nazwa pliku; Strony, Strony. Pozy strefy czasowe; Miejsca; Miejsca; Mik., nazwy plików; Nazwa Plików; Graj, Strefy czasowe; Miejsca; Miejsca; Mik., nazwy plików; Nazwa Plików; Powinnoty., Miejsca; Miejsca; Miejsca; Mik.,;
Interfejs użytkownika – czynności, przyciski, fragmenty kodu, bloki kodu, interfejs wiersza poleceń, dialogi, menu i listy rozwijane, wyskakujące okienka i alerty, karty, terminologia, elementy interfejsu, okna
Kod – CSS, HTML, JS, Markdown, MySQL, PHP, składnia, XML
Słownik/glosariusz z wyrazami od A do Z