Projekt Bokeh

Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.

Podsumowanie projektu

Organizacja open source:

Bokej

Pisarz techniczny:

vis_verborum

Nazwa projektu:

Tworzenie, czytanie, udostępnianie: dokumentacja optymalizacji Bokeh

Długość projektu:

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

Opis projektu

Tworzenie, czytanie, udostępnianie: dokumentacja optymalizacji Bokeh

1. W skrócie

Bokeh to niezwykle zaawansowane narzędzie do tworzenia interaktywnych wizualizacji w przeglądarce w Pythonie. Ma sporą bazę użytkowników (502 tys. pobrań miesięcznie i 855 tys. pobrań w PyPi) oraz dużą liczbę współtwórców (455 współtwórców z GitHuba). Nic dziwnego, że obszerna dokumentacja Bokeh automatycznie się rozwija. A przez to w niespójnych, trudnych do opanowania i nieporozumień.

Sezon dokumentów Google to wyjątkowa okazja, aby dokładnie przejrzeć i zredagować strukturę oraz treść dokumentacji Bokeh. Dokumentacja oraz powiązane z nią narzędzia i procesy będą gotowe na przyszłość.

Napisałem kod i udokumentowałem projekty open source w językach Python i Sfinx (ostatnio: PyZillow i PyPresseportal). Ale to, co mnie wyróżnia w tym sezonie, to moje wykształcenie w branży dziennikarskiej – od ponad 13 lat pracuję w redakcjach, w tym przez wiele lat jako redaktor zarządzający i działam na rzecz zmian cyfrowych. Oprócz moich obowiązków dziennikarskich, wiązałam się z większymi obowiązkami projektowania i dokumentowania nowych narzędzi cyfrowych i wskazówek stylistycznych, a także szkoleniem pracowników redakcji.

Po niedawnym przeprowadzce z Europy do Stanów Zjednoczonych postanowiłam odkryć nowe sposoby na połączenie mojego entuzjazmu w zakresie komunikacji i kodowania. Artykuł techniczny uznałem za optymalne połączenie moich umiejętności i doświadczenia technicznego. W ramach tej oferty przedstawię, jak będę korzystać z sezonu dokumentów Google do optymalizacji dokumentacji Bokeha: w ten sposób ułatwię tworzenie dokumentacji i dodawanie jej do niej osób, ułatwiając odczytywanie dokumentacji i ułatwiając udostępnianie zawartych w niej informacji innym osobom.

2. Obecna sytuacja

Oficjalna dokumentacja Bokeh składa się z tych głównych jednostek:

• Dokumentacja: Przewodnik instalacji, Przewodnik użytkownika, Przewodnik dla programistów, informacje o wersji
• Galeria i wersje demonstracyjne (interaktywne przykłady zawierające kod źródłowy)
• Przewodnik (dokumentacja oparta na dokumentach),
• Samouczek (szeroka kolekcja notatników Jupyter, hostowana na mybinder.org)
• Pomoc dotycząca łańcuchów dokumentów i modeli dla IDE
• Przykłady i pliki README w repozytorium projektu

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

Większość stron z dokumentacją jest tworzona w aplikacji Sphinx przy użyciu kilku standardowych i niestandardowych rozszerzeń Sphinx. Na przykład Przewodnik referencyjny jest generowany na podstawie ciągów dokumentów za pomocą rozszerzeń takich jak „autodoc” i niestandardowy „bokeh_autodoc”. Podobnie jak w przypadku dokumentacji rozwojowej, zawiera ona zbędne elementy i niespójności.

Jedną z pierwszych rzeczy, jakie zauważyłam przy analizowaniu istniejącej dokumentacji, był brak jasnych wytycznych dotyczących stylu pisania dokumentacji. Przewodnik dla programistów Bokeh zawiera kilka podstawowych instrukcji. W tym dokumencie nie ma jednak zbyt wielu wskazówek dotyczących stylu, zwłaszcza w zakresie dokumentacji, która wykracza poza serie ciągów. W efekcie problemy stylistyczne i strukturalne utrudniają dostęp do informacji w dokumentach, zwłaszcza początkującym.

Na przykład:

• Użycie rzeczowników, myślników i nietypowych słów zamiast zrozumiałych i mocnych czasowników sprawia, że część tekstu staje się niepotrzebnie skomplikowana: „Chodzi o to, że typowe zastosowanie obejmuje tworzenie obiektów fabuły za pomocą funkcji figur()”. Należy je sformułować, aby ułatwić czytanie. Na przykład: „Funkcja figur() to funkcja najczęściej używana do tworzenia obiektów na wykresie”.
• Niektóre zdania są bardzo długie, co utrudnia ich zrozumienie: „Następnie możemy wywołać funkcję vbar z listą współczynników nazw owoców jako współrzędnej X, wysokości słupka jako współrzędnej górnej i opcjonalnie szerokości lub innych właściwości, które chcemy skonfigurować”. Dłuższe zdania powinny być podzielone na krótsze zdania lub listy punktowane. Uproszczone zdania będą szczególnie przydatne dla użytkowników z dysleksją lub osób, które nie używają angielskiego jako języka ojczystego (patrz problem #10160).
• Niespójne użycie słów „Ty” i „my”, co jest mylące i dezorientuje: „W zależności od konkretnego przypadku użycia można użyć 2 podstawowych metod i „Możemy stworzyć zestawienie całej serii z całego roku, korzystając z osobnych połączeń” (2 przykłady z tej samej strony). Niektóre strony są kierowane do czytelników na różne sposoby, np. „użytkownicy mogą być zmuszeni zainstalować dodatkowe zależności” lub „można tworzyć bardziej złożone układy”.
• Litery, brakujące i zbędne słowa oraz błędy gramatyczne zaburzają przebieg czytania i podważają wiarygodność informacji: „Bokeh ułatwia tworzenie podstawowych wykresów słupkowych” lub „Zobacz sekcję glify w przewodniku użytkownika”.
• Niespójności strukturalne mogą być frustrujące dla czytelników, np. przykłady dobrze opisane z adnotacjami na jednej stronie i brak objaśnienia przykładów na innej stronie.

Strona dokumentacji Bokeh jest raczej krótka i nie zawiera informacji o wszystkich dostępnych zasobach (nie wspomina o rozległej bibliotece funkcji pomocy dotyczących modeli i dokumentów, forach pomocy, prezentacjach ani blogu Medium). Utrudni to też nowym użytkownikom rozpoczęcie korzystania z efektu Bokeh.

3. Gole

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

3.1. Usprawnij tworzenie dokumentów

Większość dokumentacji Bokeh tworzą osoby, które dokładają dokumentację jako część żądań pull dotyczących nowych funkcji i poprawek. Podczas gdy część fazy tworzenia dokumentów będę zajmować się ich edytowaniem i refaktoryzacją, skupiam się na tworzeniu przepływów pracy służących tworzeniu i przechowywaniu dokumentacji na przyszłość. Dążę do tego, aby osoby odpowiedzialne za tworzenie dokumentacji utrzymywały niezmiennie wysoki standard dokumentów.

Zajmę się tym na 2 sposoby:

• Utworzę zestaw praktycznych i prostych wskazówek dotyczących stylu, które będą dostępne w obecnym przewodniku dla programistów. Wytyczne dotyczą stylu, gramatyki i struktury. Będę też korzystać z wewnętrznych kanałów komunikacji, takich jak Slack, aby mieć pewność, że współtwórcy Bokeh znają wytyczne dotyczące stylu. Przeprowadzę też indywidualne szkolenie oraz sesje pytań i odpowiedzi dla zespołu.
• Będę współpracować z podstawowym zespołem w celu znalezienia optymalnego zestawu narzędzi do kontroli jakości dokumentacji, które zostaną dodane do dotychczasowych przepływów pracy Bokeh dotyczących żądań PR (żądań pull) i CI (stała integracja). W zależności od wymagań zespołu może to być dodanie do zestawu testów Bokeh takich narzędzi jak pydocstyle, proselint czy sphinxcontrib-spelling do zestawu testów Bokeh, konfiguracja wstępnego zatwierdzenia lub działania na GitHubie. Dodałem działający model koncepcyjny do działań GitHub w jednym z moich własnych projektów open source.

3.2. Usprawnij czytanie dokumentów

Celem dobrej dokumentacji jest ułatwienie obecnym i przyszłym użytkownikom znalezienia dokładnych informacji i jak najbardziej efektywne wykorzystanie tych danych.

Głównymi czynnikami wpływającymi na użyteczność tekstu jest jego styl i struktura. Stworzenie przejrzystego, spójnego stylu pozwala czytelnikom na szybkie przyswojenie informacji bez rozpraszania i narzucania zbędnego języka. Prosta i przejrzysta struktura dokumentacji ułatwia szybkie wyszukiwanie istotnych informacji.

Skoncentruję się na obu tych obszarach, skupiając się na łatwości obsługi przez nowych użytkowników. Obejmuje to dokładne zapoznanie się z dokumentacją narracyjną wyśrodkowaną na przewodniku użytkownika. Ulepszę też stronę docelową z dokumentacją, aby wyraźniej dotrzeć do różnych grup odbiorców i zadbać o to, aby każdy użytkownik mógł szybko znaleźć odpowiednie materiały.

Tak jak przy udoskonalaniu tworzenia dokumentów opisanych powyżej, skoncentruję się na budowaniu podstawy dla przyszłych ulepszeń i stale wysokich standardów dokumentacji Bokeh.

3.3. Usprawnij udostępnianie dokumentów

Coraz więcej osób dyskutuje na temat Bokeh na platformach zewnętrznych. Wiele z tych platform korzysta z metadanych takich jak OpenGraph Facebooka, aby wyświetlać podgląd linków w formie multimedialnej. Z OpenGraph korzystają takie usługi jak Facebook, Twitter, LinkedIn, Slack i iMessage. Forum Bokeh Discourse korzysta też z OpenGraph do renderowania linków.

Aby skorzystać z tej technologii, dodaję metadane do stron internetowych wygenerowanych przez Bokeh wygenerowanego przez sfinksa zgodnie z opisem w numerze #9792. Najefektywniejszym sposobem jest wykorzystanie dedykowanego rozszerzenia Sphinx. Kilka dni temu w serwisie GitHub opublikowano pierwszą wersję rozszerzenia Sphinx do obsługi danych OpenGraph. Wykorzystam część fazy tworzenia dokumentacji, aby pomóc w ulepszaniu tego rozszerzenia na potrzeby dokumentacji Bokeh.

Opracowałam także model koncepcyjny, który z powodzeniem wykorzystujem w jednym z własnych projektów open source – PyPresseportal. To rozszerzenie automatycznie zbiera istotne informacje, takie jak tytuł, opis, obraz i adres URL. Następnie wstawia te informacje do kodu HTML wygenerowanego przez Sphinxa jako tagi OpenGraph.

Kolejnym etapem opracowywania tego rozszerzenia jest wprowadzenie niestandardowych dyrektyw w celu ręcznego definiowania metadanych OpenGraph (podobnie jak w przypadku istniejących dyrektyw „meta” programu docutil). Metadane wygenerowane automatycznie będą używane tylko jako dane zastępcze, jeśli dane wpisane ręcznie nie będą dostępne.

Obsługa uporządkowanych danych jest znacznie bardziej złożona, dlatego skupię się głównie na dołączaniu wysokiej jakości metadanych OpenGraph do dokumentacji Bokeh. Wszystkie wysiłki związane z obsługą OpenGraph będą jednocześnie podstawą obsługi uporządkowanych danych.

Członkowie społeczności Sphinx i ReadTheDokumentacja wyrazili zainteresowanie opracowaniem rozszerzeń dla OpenGraph i uporządkowanych danych (np. w problemach #1758 i #5208). Będę z nimi ściśle współpracować.

4. Twoje zobowiązanie

Podsumowując, oto elementy, które powinny pojawić się w sezonie Dokumentów:

• Wytyczne dotyczące stylu dokumentacji dla współtwórców obrazu Bokeh
• Ulepszenie procedur PR i CI, aby uwzględnić zautomatyzowaną kontrolę jakości dokumentacji.
• Zredagowany i zmieniony Przewodnik użytkownika
• Zmodyfikowana strona docelowa dokumentacji
• Metadane Open Graph zawarte na stronach internetowych z dokumentacją oraz działające rozszerzenie Sphinx

Prowadzę też „doclog”, aby dokumentować moją podróż w sezonie Dokumentów Google na swojej osobistej stronie internetowej/Medium lub blogu Bokeh’s Medium. Na podstawie tych informacji stworzymy dla Google raport o projekcie. Będę przystępować do wszystkich działań w sposób przejrzysty, w formie problemów z GitHubem i żądań pull, gdy tylko będzie to możliwe.

5. Oś czasu

Przed rozpoczęciem budowania więzi ze społecznością: biorę już udział w kilku dyskusjach na temat repozytorium Bokeh na GitHubie i nawiązałem kontakt z Bryanem Van de Venem i Pavithrą Eswaramoorthy, mentorami zespołu Bokeh w sezonie dokumentów Google. Będę aktywnie uczestniczyć w rozmowach na temat Bokeh. Będę się też dokładniej zapoznawać z efektem Bokeh, tworząc i publikując wizualizacje.

Etap budowania więzi ze społecznością (17.08–13.09):

• Poznaj podstawowy zespół, dopracuj plan projektu w zamian z mentorami
• Opracować harmonogram i kanały komunikacji, aby regularnie przesyłać raporty i poznawać opinie mentorów
• Aktywnie korzystaj z platformy Slack na platformie Bokeh, aby informować wszystkich zainteresowanych współtwórców Bokeh o sezonie Dokumentów Google i celach fazy opracowywania dokumentu.
• Zbierz opinie od współtwórców projektu Bokeh, aby dopracować plan fazy opracowywania dokumentu.

Faza tworzenia dokumentu

Tydzień 1, 14–20 września:

• Rozpocznij sprawdzanie i edytowanie dokumentacji narracji
• Rozpocznij tworzenie wersji roboczej wytycznych dotyczących stylu

Tydzień 2, 21–27 września:

• Kontynuuj pracę nad wskazówkami dotyczącymi stylu
• Kontynuuj edytowanie dokumentacji narracji
• Rozpocznij modernizację strony docelowej dokumentacji

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

• Dokończ wytyczne dotyczące stylu
• Sfinalizuj stronę docelową dokumentacji

Tydzień 4, 5 października – 11 października:

• Dokończ edytowanie dokumentacji narracji
• Omów z głównym zespołem Bokeh narzędzia do kontroli jakości dokumentów w przepływach pracy PR/CI

Tydzień 5, 12–18 października:

• Przygotuj sesję pytań i odpowiedzi ze współtwórcami Bokeh na Slacku, aby omówić wskazówki dotyczące stylu, ulepszenia dokumentacji dotyczącej narracji i przepływów pracy PR/CI.
• Zacznij opracowywać istniejący model koncepcyjny metadanych OpenGraph na potrzeby wdrożenia rozszerzenia Sphinx.
• Zmiana wytycznych dotyczących stylu na podstawie opinii z sesji pytań i odpowiedzi z twórcami bokeh

Tydzień 6, 19.10–25.10:

• Rozpocznij testowanie narzędzi do kontroli jakości dokumentów w przepływach PR i CI
• Kontynuuj tworzenie rozszerzenia Sphinx dla metadanych

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

• Testowanie rozszerzenia Sphinx
• Druga sesja pytań i odpowiedzi z udziałem współtwórców Bokeh na Slacku
• Poprawić treści na podstawie opinii z drugiej sesji pytań i odpowiedzi

Tydzień 8, 2–8 listopada:

• Wdróż rozszerzenie Sphinx i opublikuj ulepszoną dokumentację narracyjną oraz stronę docelową z dokumentacją

Tydzień 9, 9.11–15.11:

• Wdrażanie narzędzi kontroli jakości dokumentów w przepływach pracy PR i CI
• Zaktualizuj i opublikuj Przewodnik dla programistów, aby uwzględnić w nim wskazówki dotyczące stylu oraz nowe przepływy pracy PR i CI

Tydzień 10, 16.11–22.11:

• Dokończ pozostałe zadania

Tydzień 11, 23 listopada – 29 listopada:

• Zacznij pisać raport z projektu
• Rozpocznij pisanie oceny projektu

Etap finalizacji projektu

Tydzień 12, 30 listopada – 5 grudnia:

• Finalizowanie i przesyłanie raportu dotyczącego projektu

Tydzień 13, 3–10 grudnia:

• Dokończ i prześlij ocenę projektu

Po zakończeniu Sezonu Dokumentów Google:

• Mam nadzieję nadal angażować się w rozwój Bokeh i nadal pracować nad jego dokumentacją.
• Zamierzam w dalszym ciągu pracować nad rozszerzeniem Sphinx dotyczącym metadanych OpenGraph/uporządkowanych danych.
• Mam nadzieję wykorzystać swoje doświadczenie w dziennikarstwie i moją dotychczasową sieć kontaktów, aby promować Bokeh jako narzędzie do dziennikarstwa opartego na danych. Możesz na przykład pisać o Bokeh z myślą o odbiorcach dziennikarskich lub wygłaszać prelekcje na temat wykorzystania efektu Bokeh w środowiskach dziennikarskich.

6. O mnie

Zajmuję się głównie dziennikarstwem. Zajmuję się wiadomościami w telewizji, internecie i radiu. Pracuję jako redaktor naczelna i reporter w telewizji i wiadomościach cyfrowych, co pozwoliło mi wiele lat doświadczenia w pisaniu i redagowaniu. W tym samym czasie realizowałam kilka projektów promujących transformację cyfrową i automatyzację. Napisałam wiele podręczników, w których omawiano narzędzia i procesy cyfrowe, a także poradniki stylistyczne i strategie komunikacji dla marek z branży wiadomości cyfrowych. Przeszkoliłem też członków zespołu w korzystaniu z tych narzędzi.

Zawsze interesowała mnie granica komunikacji i technologii. Gdy nauczyłam się kodowania w Pythonie, otworzyła mi się całkiem nowy świat: potrafię analizować i wizualizować dane na przykład w dziennikarstwie opartym na danych. Nauka kodowania pozwoliła mi także aktywnie współpracować z inżynierami oprogramowania przy opracowywaniu narzędzi cyfrowych na potrzeby przepływów pracy w redakcji.

Podręczniki i dokumenty napisane przeze mnie w poprzednim miejscu pracy są niestety niedostępne. Teraz skoncentruję się na projektach open source (przykłady znajdziesz poniżej). Swoją pracę piszę w oparciu o wskazówki techniczne, takie jak wskazówki redakcyjne opracowane przez Google i wskazówki redakcyjne firmy Microsoft. Regularnie korzystam z GitHuba, Slacka i Linuksa. Pisałam dokumentację narracyjną, streszczenia dokumentów oraz wskazówki dotyczące pisania przy użyciu narzędzi takich jak Sphinx, Mypy i Sfinx.

Jestem obecnie freelancerem. Mój harmonogram zapewnia elastyczność niezbędną do pracy nad dokumentacją Bokeh przez około 25 godzin tygodniowo w trakcie fazy opracowywania dokumentu. Pracuję w strefie czasowej pacyficznej, ale chętnie pomogę ustalić harmonogram i potrzeby zespołu.

7. Najnowsze przykłady dokumentacji open source

• PyZillow PyZillow to opakowanie Pythona dla interfejsu API witryny Zillow.com z branży nieruchomości. Oprócz udostępnienia kodu i pełnienia roli jednego z opiekunów kodu, opracowałem pełną dokumentację. Sfinks został użyty w dokumentacji narracji oraz jako materiały referencyjne modułu. Odwołanie do modułu zostało utworzone za pomocą automatycznego dokumentu dotyczącego rozszerzenia Sphinx na podstawie ciągów dokumentacyjnych dodanych do kodu.

• PyPresseportal PyPresseportal to kod języka Pythona powiązany z interfejsem API witryny presseportal.de. Witryna Presseportal.de to jeden z największych dystrybutorów komunikatów prasowych i ogłoszeń dotyczących relacji z inwestorami 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 jako dziennikarz postanowiłem stworzyć interfejs Pythona, który umożliwi dostęp do obszernych zasobów danych witryny w postaci obiektów Pythona. Kod oraz cała dokumentacja oparta na usłudze Sphinx zostały napisane przeze mnie.