Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- WordPress
- Pisarz techniczny:
- tacytoton
- Nazwa projektu:
- Pełny i odnowiony zestaw dokumentacji
- Długość projektu:
- Długotrwałe (5 miesięcy)
Opis projektu
Streszczenie:
WordPress to globalna organizacja non-profit zajmującego się tworzeniem oprogramowania, która oferuje społecznościom na całym świecie oprogramowanie podkreślające dostępność, wydajność, bezpieczeństwo i łatwość użycia. Celem WordPressa jest demokratyzacja publikowania i rozwijania oprogramowania typu open source w internecie. W epoce cyfrowej witryna stanowi w dużej mierze internetowej fasadę organizacji/osoby fizycznej, a WordPress służy do efektywnej obsługi setek milionów użytkowników korzystających z jego oprogramowania (przypisane do 35% całego internetu). Aby móc efektywniej służyć takim użytkownikom, dokumentacja okazuje się niezbędna i jest używana przez większość deweloperów, administratorów i użytkowników. W związku z tym dokumentacja może stanowić główny czynnik decydujący o ekosystemie WordPress. Obecna dokumentacja WordPress nie zawiera uniwersalnego i ujednoliconego zestawu reguł oraz wytycznych dotyczących stylu. Celem tej propozycji jest stworzenie pełnego i odnowionego zestawu wytycznych dotyczących stylu dokumentacji, mających zastosowanie w przypadku dokumentacji WordPress. Pomysł na projekt obejmuje konsolidację wszystkich aspektów wskazówek dotyczących stylu i projektu, takich jak semantyka, składnia, zasady gramatyczne, interpunkcja, reguły obowiązujące w przypadku tworzenia, atrybuty projektowe i ustawienia formatowania. Uwzględnia też konwencje językowe, takie jak głos, ton, czas i wszystkie części mowy, a także konwencje nazewnictwa. Używane są następujące narzędzia, języki i platformy: WordPress CMS, GitHub i Markdown, a także mogą zawierać języki PHP/MySQL, HTML/CSS i JavaScript.
Plan projektu:
Aktualne przewodniki po stylu dokumentacji WordPress: Zespół ds. dokumentacji WordPress wdrożył niezadeklarowaną, ale jednomyślną metodologię wytycznych dotyczących publikowania. Od czasu do czasu jednak pewne elementy przyjmują pewne założenia, a proces ten staje się spekulacyjny. Nie ma żadnych stałych standardów i kryteriów używanych do pisania i publikowania artykułów w WordPressie. Zespół ds. dokumentacji opracował wskazówki dotyczące stylu odnoszące się do konkretnego projektu, ale nie są one uniwersalne. Większość istniejących wytycznych dotyczących stylu nie jest skonsolidowana w jednym podręczniku lub została wycofana i trzeba je zaktualizować. W związku z tym istnieje potrzeba opracowania i opracowania ujednoliconego przewodnika stylu, który pozwoli ujednolicić dokumentację WordPress.
Cele:
Ponad 35% stron internetowych jest opartych na WordPressie, co z kolei wskazuje, że z imponujących funkcji tej platformy korzystają miliony deweloperów i użytkowników. Dokumentacja jest kluczowym elementem, który pomaga tym programistom i użytkownikom sprawnie realizować te funkcje, nawet jeśli występują w nich niedogodności. Ogólnym celem tego projektu jest ujednolicenie wskazówek dotyczących projektowania i stylu, ujednolicenie istniejących przewodników stylistycznych i zaktualizowanie ich, a także dodanie nowych przepisów i specyfikacji dotyczących dokumentacji WordPress. Zwiększy to wygodę użytkowania i ujednolicenie dokumentacji WordPressa.
Wdrożenie:
Zgodnie z sugestią mentora (Jon Ang) w tym projekcie projekt można realizować w 4 fazach: odkrywanie, definicja, wdrażanie i konserwacja. Przed rozpoczęciem projektu, w trakcie okresu poprzedzającego staż, wspólnie z mentorem ustalimy odpowiedni harmonogram i harmonogram realizacji zgodnie z harmonogramem i materiałami do dostarczenia. Dokładnie poznam system WordPress i protokoły robocze używane w tym projekcie.
W miarę rozpoczęcia stażu wraz z mentorem omówię z mentorem streszczenie projektu oraz przygotuję jego wersję roboczą. Zostaną one określone. Najpierw zaprezentuję przepływ dokumentacji oraz proces interakcji użytkownika. Następnie zostaną przedstawione schematy układu dla każdej sekcji, kategorii i komponentu. Układy zostaną sprawdzone przez mojego mentora. W razie potrzeby zmienimy układ i dodamy lub usuniemy niektóre komponenty. Następnie przeprowadzę badania użytkowników, aby określić użyteczność i wykonalność interfejsu. Następnie w każdej sekcji zostanie wdrożony Przewodnik po stylu dokumentacji (jak pokazano na diagramie poniżej). Do naszego przewodnika można również dołączyć wskazówki redakcyjne opublikowane przez inne organizacje korzystające z licencji open source lub Creative Commons. Jeśli w tym czasie wystąpią jakiekolwiek problemy z obsługą, przeprojektujemy je.
Testowanie i optymalizacje zostaną przeprowadzone po wypełnieniu przewodnika stylistycznego i zintegrowaniu go z HelpHub. Wszelkie luki w zabezpieczeniach oraz zbędne elementy i komponenty zostaną usunięte. Zostaną przeprowadzone testy interfejsu użytkownika i kodu, a w razie potrzeby zostaną usunięte niechciane błędy i błędy. Zostanie przeprowadzona ostateczna ocena jakości wszystkich wskazówek dotyczących języka, gramatyki, pisowni, interpunkcji itp.
Zadania oczekujące z powodu nieprzewidzianych opóźnień są wykonywane w okresie bufora. Dodatkowe funkcje, które zostaną uznane za możliwe w trakcie realizacji projektu, można wdrożyć po zakończeniu testów końcowych. Zostanie utworzony plan wdrożenia, a następnie zostanie przesłany gotowy produkt.
Narzędzia i metody:
Dokumentacja jest kompilowana i edytowana na platformie współpracy, np. w Dokumentach Google. Jeśli musisz publikować za pomocą GitHuba, możesz też zastosować języki znaczników, takie jak Markdown lub GitHub Flavored Markdown. W przypadku standardów dotyczących wzornictwa i stylu można się również odwoływać do wytycznych dotyczących stylu open source. Na koniec sformatujemy i opublikujesz gotowy dokument za pomocą WordPressa.
Tabela składników:
Poniżej znajduje się wyczerpująca lista komponentów, które można wdrożyć za pomocą tego przewodnika. Wskazówki dotyczące dokumentu – ułatwienia dostępu, struktura dokumentu, kodowanie, źródła zewnętrzne, fakty, czcionki, odbiorcy globalni, integracja społeczna, legalność, dostępność na wielu platformach, niejednoznaczne, brak nadmiernych twierdzeń, układ strony, prawidłowość 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 negatywy, artykuły, wielkie litery, klauzula, mowa bezpośrednia/pośrednia, pierwsza/druga/trzecia osoba, płcie, glosariusz, rzeczowniki, prefiksy i sufiksy, przyimki, zaimki, odniesienia, slang, żargon, pisownia i slang, język słowny
Interpunkcja – apostrofy i cudzysłowy, dwukropki, dwukropki, przecinki, elipsy, wykrzykniki, łączniki i kreski, nawiasy, kropki, znaki zapytania, ukośniki
Formatowanie znaków towarowych, Streszczenia, Wprowadzenie, Nazwy w formie numerów, Nazwy marek, Nazwy produktów, Napisy, Fragmenty kodu, bloki kodu, Data i godzina, Strefy czasowe, Miejsca, Nazwy plików, Przypisy, Nagłówki i tytuły, Wyróżnienia (pogrubienie, Kursywa, Podkreślenie, Przekreślenie, Notatki, Nazwy i tytuły), Streszczenie, Streszczenie, Nazwy plików, Przypisy, Nagłówki i tytuły.
Interfejs – działania, przyciski, fragmenty kodu, bloki kodu, interfejs wiersza poleceń, okna, menu i menu, wyskakujące okienka i alerty, karty, terminologia, elementy interfejsu, okna
Kod – CSS, HTML, JS, Markdown, MySQL, PHP, składnia oraz XML.
Słownik użytkowania słów