Projekt Bokeh

Ta strona zawiera szczegółowe informacje o projekcie polegającym na pisaniu tekstów technicznych, który został zaakceptowany w ramach Google Season of Docs.

Podsumowanie projektu

Organizacja open source:

Bokeh

Specjalista ds. technicznych:

vis_verborum

Nazwa projektu:

Tworzenie, czytanie i udostępnianie: optymalizacja dokumentacji Bokeh

Długość projektu:

Standardowa długość (3 miesiące)

Opis projektu

Tworzenie, czytanie i udostępnianie: optymalizacja dokumentacji Bokeh

1. Streszczenie

Bokeh to bardzo wydajne narzędzie do tworzenia interaktywnych wizualizacji w przeglądarce za pomocą Pythona. Ma dużą bazę użytkowników (502 tys. pobrań conda miesięcznie, 855 tys. pobrań PyPi) i dużą liczbę współtwórców (455 współtwórców na GitHubie). Nie dziwi, że obszerna dokumentacja Bokeh rozwija się w sposób organiczny. W efekcie w niektórych miejscach są one niespójne, trudne do znalezienia i skomplikowane.

Sezon Dokumentacji w Google to wyjątkowa okazja do dokładnego sprawdzenia i zrewidowania struktury i treści dokumentacji Bokeh oraz upewnienia się, że dokumentacja i powiązane z nią narzędzia i przepływy pracy są gotowe na przyszłość.

Napisałem i opisałem projekty open source za pomocą Pythona i Sphinxa (ostatnio: PyZillow i PyPresseportal). Jednak to, co wyróżnia mnie wśród uczestników Google Season of Docs, to moje doświadczenie w dziennikarstwie. Pracowałam w redakcjach przez ponad 13 lat, przez wiele lat jako redaktor naczelna i zwolenniczka zmian cyfrowych. Oprócz pełnienia obowiązków dziennikarskich zajmowałem się projektowaniem i dokumentowaniem nowych narzędzi cyfrowych i przewodników redakcyjnych, a także szkoleniem pracowników redakcji.

Po niedawnym przeprowadzce z Europy do USA postanowiłam znaleźć nowe sposoby na połączenie mojego entuzjazmu dotyczącego komunikacji i programowania. Pismo techniczne stanowi optymalne połączenie moich umiejętności i doświadczenia w pisaniu tekstów technicznych. W ramach tej propozycji chcę przedstawić, jak wykorzystam Sezon Dokumentów Google do optymalizacji dokumentacji Bokeh: tworzenie dokumentacji i wkład w nią wkład w jej opracowywanie – łatwiejsze czytanie i udostępnianie informacji innym użytkownikom.

2. Obecna sytuacja

Oficjalna dokumentacja Bokeh obejmuje te główne jednostki:

• Dokumentacja tekstowa: przewodnik instalatora, przewodnik użytkownika, przewodnik dla programistów, notatki do wersji.
• Galeria i wersje demonstracyjne (interaktywne przykłady z kodem źródłowym)
• Przewodnik referencyjny (dokumentacja oparta na opisie funkcji)
• Samouczek (obszerna kolekcja notatników Jupyter hostowanych na mybinder.org)
• Pomoc dotycząca ciągów dokumentów i modelu w IDE
• przykłady i pliki README w repozytorium projektu;

Dodatkowo wiele informacji jest dostępnych na forum pomocy Bokeh i na Stack Overflow, gdzie deweloper Bokeh aktywnie odpowiada na pytania użytkowników, a także na blogu Bokeh na Medium.

Większość stron internetowych dokumentacji jest tworzona za pomocą Sphinxa przy użyciu kilku standardowych i niestandardowych rozszerzeń Sphinxa. Przewodnik referencyjny jest na przykład generowany z docstringsów za pomocą rozszerzeń takich jak „autodoc” i niestandardowego „bokeh_autodoc”. Podobnie jak inne dokumenty, które powstają w sposób nieformalny, zawiera on duplikaty i niespójności.

Jedną z pierwszych rzeczy, które zauważyłam podczas analizowania istniejącej dokumentacji, był brak jasnych wytycznych dotyczących stylu pisania dokumentacji. Przewodnik dla programistów Bokeh zawiera podstawowe instrukcje. Nie zawiera on jednak zbyt wielu wskazówek dotyczących stylu, zwłaszcza w przypadku dokumentacji wykraczającej poza opisy funkcji. W konsekwencji problemy ze stylistyką i strukturą utrudniają dostęp do informacji zawartych w dokumentach, zwłaszcza osobom dopiero zaczynającym naukę języka.

Na przykład:

• Używanie rzeczowników, czasowników i rzadkich słów zamiast wyraźnych i mocnych czasowników sprawia, że część tekstu jest niepotrzebnie skomplikowana: „Główna obserwacja polega na tym, że typowe użycie polega na tworzeniu obiektów fabuły za pomocą funkcji rysunek()”. Trzeba to zmienić, aby ułatwić czytanie. Na przykład: „Funkcja figure() jest najczęściej używaną funkcją do tworzenia obiektów wykresów”.
• Niektóre zdania są bardzo długie, przez co trudno je zrozumieć: „Następnie możemy wywołać vbar z listą czynników nazw owoców jako współrzędna x, wysokość paska jako górna współrzędna i opcjonalnie dowolną szerokość lub inne właściwości, które chcemy ustawić”. Dłuższe zdania należy podzielić na krótsze zdania lub listy wypunktowane. Upraszczanie zdań będzie szczególnie przydatne dla osób z dysleksją lub dla tych, dla których angielski nie jest językiem ojczystym (patrz problem #10160).
• Niespójność w używaniu „ty” i „my”, która wprowadza zamieszanie i rozprasza uwagę: „W zależności od przypadku użycia możesz użyć jednej z 2 podstawowych metod” i „Możemy narysować wszystkie serie roku za pomocą oddzielnych wywołań” (2 przykłady z tej samej strony). Niektóre strony zwracają się do czytelników na wiele różnych sposobów, np.: „może być konieczne zainstalowanie dodatkowych zależności” lub „można utworzyć bardziej złożone układy”.
• Błędy literowe, brakujące lub zbędne słowa oraz błędy gramatyczne zakłócają płynność czytania i podważają wiarygodność informacji: „Bokeh ułatwia tworzenie podstawowych wykresów słupkowych” lub „Zobacz sekcję Glyphs w Przewodniku użytkownika”.
• Niespójności strukturalne mogą być frustrujące dla czytelników. Na przykład dobrze opisane przykłady na jednej stronie i brak wyjaśnień przykładów na innej stronie.

Strona docelowa dokumentacji Bokeh jest dość krótka i nie zawiera informacji o wszystkich dostępnych zasobach (nie ma w niej wzmianki o obszernej bibliotece docstrings i funkcji pomocy dotyczącej modelu, forach pomocy, prezentacjach ani blogu Medium). Utrudnia to też nowym użytkownikom rozpoczęcie pracy z Bokeh.

3. Cele

Aby jak najlepiej wykorzystać 11-tygodniową fazę tworzenia dokumentów, skupię się na 3 kluczowych elementach:

3.1. Ulepszenie tworzenia dokumentów

Większość dokumentacji Bokeh jest tworzona przez współtwórców, którzy dołączają ją do pull requestów dotyczących nowych funkcji i poprawek błędów. Część fazy tworzenia dokumentacji poświęcę na edytowanie i refaktoryzację istniejących dokumentów, ale przede wszystkim skupię się na tym, aby proces tworzenia i utrzymywania dokumentacji był przyszłościowy. Powinien on być jak najprostszy, aby autorzy mogli utrzymywać wysoki standard dokumentacji.

Aby to osiągnąć:

• Utworzę praktyczne, proste wytyczne dotyczące stylu, które zostaną zamieszczone w dotychczasowym Przewodniku dla programistów. Te wskazówki dotyczą stylu, gramatyki i struktury. Dodatkowo będę korzystać z wewnętrznych kanałów komunikacji, takich jak Slack, aby mieć pewność, że autorzy Bokeh znają wytyczne dotyczące stylu. Zorganizuję też dla zespołu indywidualne szkolenie oraz sesje pytań i odpowiedzi.
• Współpracując z głównym zespołem, znajdę optymalny zestaw narzędzi do kontroli jakości dokumentacji, który zostanie dodany do istniejących przepływów pracy Bokeh dotyczących PR (pull request) i CI (ciągłego integrowania). W zależności od wymagań zespołu może to oznaczać dodanie narzędzi takich jak pydocstyle, proselint czy sphinxcontrib-spelling do zestawu testów Bokeh, konfiguracji przed potwierdzeniem lub działań w GitHub. Do działań GitHuba w jednym z moich projektów open source dodałem działający model koncepcyjny.

3.2. Poprawiaj czytanie dokumentów

Dobra dokumentacja ma ułatwiać obecnym i potencjalnym użytkownikom znajdowanie odpowiednich informacji i możliwość jak najefektywniejszego ich wykorzystania.

Kluczowymi czynnikami wpływającymi na użyteczność tekstu są jego styl i struktura: pisanie dokumentacji w jasnym, spójnym stylu pozwala czytelnikom szybko poznać informacje bez rozpraszania i zbędnego języka. Jasna i przejrzysta struktura dokumentacji ułatwia szybkie znajdowanie odpowiednich informacji.

Skupię się na obu tych kwestiach, kładąc nacisk na łatwość obsługi dla nowych użytkowników. Obejmuje to dokładne sprawdzenie dokumentacji narracyjnej, ze szczególnym uwzględnieniem Podręcznika użytkownika. Przerobię też stronę docelową dokumentacji, aby lepiej dopasować ją do różnych grup odbiorców i zadbać o to, aby każdy użytkownik mógł szybko znaleźć odpowiednie zasoby.

Podobnie jak w przypadku ulepszenia tworzenia dokumentów opisanego powyżej, będę się skupiać na tworzeniu podstawy dla przyszłych ulepszeń i utrzymywaniu wysokich standardów w dokumentacji Bokeh.

3.3 Udostępnianie dokumentów

Coraz więcej dyskusji na temat Bokeh odbywa się na platformach innych firm. Wiele z tych platform wykorzystuje metadane, np. OpenGraph Facebooka, aby wyświetlać podglądy linków z elementami rozszerzonymi. Z OpenGraph korzystają takie usługi jak Facebook, Twitter, LinkedIn, Slack i iMessage. Forum Discourse w Bokeh korzysta też z OpenGraph do renderowania podglądów linków.

Aby skorzystać z tej technologii, dodam metadane do stron internetowych generowanych przez Sphinxa w Bokeh, zgodnie z opisem w problemie #9792. Najskuteczniejszym sposobem jest użycie dedykowanego rozszerzenia Sphinx. Kilka dni temu na GitHub została opublikowana pierwsza wersja rozszerzenia Sphinxa do danych OpenGraph. W ramach fazy tworzenia dokumentacji pomogę Ci ulepszyć to rozszerzenie, aby można było z niego korzystać w dokumentacji Bokeh.

Stworzyłem też proof of concept, którego używam w jednym z moich projektów open source, PyPresseportal. To rozszerzenie automatycznie zbiera odpowiednie informacje, takie jak tytuł, opis, obraz i adres URL. Następnie wstawia te informacje do kodu HTML wygenerowanego przez Sphinxa jako tagi OpenGraph.

Następnym krokiem w rozwijaniu tego rozszerzenia będzie wprowadzenie niestandardowych dyrektyw, które pozwolą ręcznie definiować metadane OpenGraph (podobnie jak istniejące dyrektywy „meta” w docutil). Automatycznie wygenerowane metadane będą używane tylko jako dane zapasowe, gdy nie ma dostępnych danych wprowadzonych ręcznie.

Obsługa uporządkowanych danych jest znacznie bardziej skomplikowana, dlatego w dokumentacji Bokeh skupię się głównie na dodawaniu wysokiej jakości metadanych OpenGraph. Wszystkie działania związane z obsługą OpenGraph będą jednocześnie tworzyć podstawy obsługi danych uporządkowanych.

Członkowie społeczności Sphinx i ReadTheDocuments wyrazili zainteresowanie opracowywaniem rozszerzeń do OpenGraph i uporządkowanych danych (np. w numerach #1758 i #5208), dlatego na pewno będę z nimi ściśle współpracować.

4. Dostarczane materiały

Podsumowując, oto wyniki, których oczekuję po Season of Docs:

• Wytyczne dotyczące stylu dokumentacji dla autorów Bokeh
• Zmodyfikowane przepływy pracy związane z PR i CI, aby uwzględnić automatyczną kontrolę jakości dokumentacji
• Zmieniony i przekształcony Przewodnik użytkownika
• Zmieniona strona docelowa dokumentacji
• metadane OpenGraph zawarte na stronach dokumentacji i działające rozszerzenie Sphinx

Dodatkowo będę prowadzić „doclog”, aby dokumentować swoją przygodę z Dokumentami Google na mojej osobistej stronie internetowej lub na Medium albo na blogu Bokeh na Medium. Będzie to też podstawa raportu projektu dla Google. W miarę możliwości będę wykonywać wszystkie czynności w przezroczysty sposób, w formie zgłoszeń i pull request na GitHubie.

5. Oś czasu

Przed fazą tworzenia więzi ze społecznością: biorę już aktywny udział w kilku dyskusjach na temat repozytorium Bokeh na GitHubie i kontaktuję się z Bryanem Van de Venem i Pavithrą Eswaramoorthy, mentorami Bokeh w sezonie Dokumentów Google. Będę aktywnie uczestniczyć w dyskusji na temat Bokeh i udzielę się dalszej znajomości tej biblioteki, tworząc i publikując wizualizacje.

Faza budowania więzi ze społecznością (17 sierpnia – 13 września):

• Poznaj zespół główny i udoskonalaj plan projektu, współpracując z mentorami
• Skonfiguruj harmonogram i kanały komunikacji, aby regularnie przekazywać raporty i opinie mentorom
• aktywnie uczestniczyć w Slacku Bokeh, aby informować wszystkich zainteresowanych współtwórców Bokeh o Sezonie Dokumentacji Google i celach na etapie tworzenia dokumentacji;
• zebrać opinie autorów Bokeh, aby jeszcze bardziej dopraczać plan na etapie tworzenia dokumentu;

Etap tworzenia dokumentu

Tydzień 1, 14–20 września:

• Rozpoczęcie kontroli i edytowania dokumentacji dotyczącej narracji
• Rozpoczęcie opracowywania wytycznych dotyczących stylu

Tydzień 2, 21–27 września:

• Kontynuowanie pracy nad wskazówkami dotyczącymi stylu
• Kontynuowanie edytowania tekstu na potrzeby dokumentacji
• Zacznij ulepszać stronę dokumentu

Tydzień 3, 28 września – 4 października:

• Sfinalizuj wskazówki dotyczące stylu
• Kończenie strony docelowej z dokumentacją

Tydzień 4, 5–11 października:

• Sfinalizuj edytowanie dokumentacji narracyjnej
• Porozmawiaj z zespołem głównym Bokeh o integracji narzędzi do kontroli jakości dokumentów w przepływach pracy PR/CI

Tydzień 5, 12.10–18.10:

• Ustaw sesję pytań i odpowiedzi z wsp.twórcami Bokeh w Slacku, aby omówić wytyczne dotyczące stylu, ulepszenia dokumentacji narracyjnej oraz przepływy pracy związane z PR i CI
• Zacznij tworzyć mój obecny model koncepcyjny metadanych OpenGraph w możliwe do wdrożenia rozszerzenie Sphinx
• Ulepszenie wskazówek dotyczących stylu na podstawie opinii z sesji pytań i odpowiedzi z udziałem współtwórców Bokeh

Tydzień 6, 19–25 października:

• Rozpocznij testowanie narzędzi do kontroli jakości dokumentów w procesach PR i CI
• kontynuować rozwój rozszerzenia Sphinx do metadanych;

Tydzień 7, 26 października – 1 listopada:

• Testowanie rozszerzenia Sphinx
• Druga sesja pytań i odpowiedzi z udziałem twórców Bokeh w Slacku
• poprawić dostarczane materiały na podstawie opinii z drugiej sesji Pytań i odpowiedzi,

Tydzień 8, 2–08 listopada:

• Wdrożenie rozszerzenia Sphinx i opublikowanie ulepszonej dokumentacji narracyjnej oraz strony docelowej dokumentacji

Tydzień 9, 9–15 listopada:

• Wdrażanie narzędzi do kontroli jakości dokumentów w procesach PR i CI
• Zaktualizuj i opublikuj Przewodnik dla deweloperów, aby uwzględnić wskazówki dotyczące stylu oraz dodatki do przepływu pracy związanego z PR i CI

Tydzień 10, 16–22 XI:

• Zakończ pozostałe zadania

Tydzień 11, 23–29 listopada:

• Rozpoczęcie pisania raportu projektu
• Rozpocznij pisanie oceny projektu

Faza finalizacji projektu

Tydzień 12, 30 XI–5 XII:

• Finalizowanie i przesyłanie raportu projektu

Tydzień 13, 3–10 gru:

• Kończenie i przesyłanie oceny projektu

Po zakończeniu okresu Docs Season w Google:

• Mam nadzieję, że będę uczestniczyć w rozwoju Bokeh i kontynuuję pracę nad jego dokumentacją.
• Zamierzam kontynuować rozwijanie rozszerzenia Sphinxa dla metadanych OpenGraph/Structured Data.
• Mam nadzieję, że wykorzystam swoje doświadczenie w dziennikarstwie i swoją obecną sieć kontaktów, aby promować Bokeh jako narzędzie do dziennikarstwa danych. Możesz na przykład pisać o Bokeh z myślą o odbiorcach z kręgu dziennikarstwa lub prowadzić wykłady na konferencjach o używaniu Bokeh w kontekście dziennikarstwa.

6. Informacje o mnie

Początkowo zajmuję się dziennikarstwem, a doświadczeniem w telewizji i radiu. Praca jako redaktor naczelny i reporter w telewizji oraz w mediach cyfrowych pozwoliła mi zdobyć wieloletnie doświadczenie w pisaniu i redagowaniu. Jednocześnie pracowałem nad kilkoma projektami promującymi transformację cyfrową i automatyzację. Napisałam wiele podręczników dotyczących narzędzi cyfrowych i przepływów pracy, a także przewodników po stylach i strategii komunikacji dla marek cyfrowych serwisów informacyjnych. Przeszkoliłam też członków zespołu, aby korzystać z tych narzędzi.

Zawsze interesowały mnie połączenia komunikacji i technologii. Gdy nauczyłam się programować w Pythonie, otworzył się przede mną zupełnie nowy świat: mogłam na przykład prowadzić analizę i wizualizację danych na potrzeby dziennikarstwa danych. Nauczenie się programowania pozwoliło mi też aktywnie współpracować z inżynierami oprogramowania nad tworzeniem cyfrowych narzędzi do pracy w redakcji.

Niestety instrukcje i dokumenty, które napisałem w poprzedniej pracy, są niepubliczne. Dlatego teraz bardziej angażuję się w projekty open source (przykłady znajdziesz poniżej). Moja praca w zakresie pisania tekstów technicznych opiera się na takich poradnikach stylu, jak przewodnik stylu dokumentacji dla deweloperów Google i przewodnik stylu firmy Microsoft. Regularnie korzystam z GitHuba, Slacka i Linuxa. Piszę dokumentację narracyjną, a także docstrings i podpowiedzi dotyczące typów za pomocą narzędzi takich jak Sphinx, Mypy i Sphinx autodoc.

Obecnie pracuję jako freelancer. Mój harmonogram zapewnia niezbędną elastyczność do pracy nad dokumentacją Bokeha przez około 25 godzin tygodniowo na etapie tworzenia dokumentu. Pracuję w strefie czasu pacyficznego, ale z przyjemnością uwzględniam harmonogramy i potrzeby zespołu.

7. Przykłady najnowszej dokumentacji na licencji open source

• PyZillow PyZillow to owijarka Pythona dla interfejsu API witryny z nieruchomościami Zillow.com. Oprócz dostarczenia kodu i bycia jednym z jego administratorów napisałem pełną dokumentację. Jako dokumentacja narracji i materiały referencyjne do modułu wykorzystałam Sfinksa. Odniesienie do modułu zostało utworzone za pomocą autodoc, czyli rozszerzenia Sphinxa, na podstawie docstringów dodanych do kodu.

• PyPresseportal interfejs PyPresseportal to zewnętrzna implementacja interfejsu API strony presseportal.de w języku Python. Witryna presseportal.de jest jednym z największych dystrybutorów komunikatów prasowych i oświadczeń dla inwestorów w Niemczech. Na przykład niemal wszystkie policja i straż pożarna korzystają z tej usługi do dystrybucji komunikatów prasowych. Po wielu latach korzystania z interfejsu API w praktyce dziennikarskiej postanowiłem opracować interfejs Pythona, który umożliwiałby dostęp do obszernych zasobów danych witryny jako obiektów Pythona. Napisałem kod i całą dokumentację opartą na Sphinxie.