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:
- ESLint
- Pisarz techniczny:
- Khawar
- Nazwa projektu:
- Uporządkowanie/przepisanie dokumentacji konfiguracji
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Streszczenie
Celem tego projektu jest przekształcenie dokumentacji konfiguracji ESLint i utworzenie skutecznej architektury informacji. Ułatwi to nawigację oraz zwiększy użyteczność i przydatność dokumentacji.
Podsumowanie projektu W obecnej wersji dokumentacja konfiguracji ESLint (https://eslint.org/docs/user-guide/configuring) zawiera wiele informacji na jednej stronie. Pomimo obecności nagłówków, podnagłówków i odpowiednich akapitów na stronie dokumentacja może przytłoczyć. Nie ma możliwości przejścia do konkretnej sekcji strony, co jest frustrujące dla użytkownika zainteresowanego daną sekcją. Z powodu braku organizacji informacje mogą się zgubić, nie spełniając swojego celu i wymagając od użytkowników dodatkowego wysiłku.
Te problemy można jednak rozwiązać, wykonując serię czynności. Pierwszym krokiem w tej reorganizacji jest audyt treści. Audyt treści pomoże nie tylko zidentyfikować problemy z prezentacją informacji, ale też wykazać niedociągnięcia w samych treściach (np. nieaktualne lub niekompletne informacje). Następnie planuję stworzyć architekturę informacji (IA), by odkryć sieć wiedzy. Dzięki temu będziemy mogli pogrupować informacje według różnych tematów i znaleźć powiązania między różnymi zagadnieniami ściśle powiązanymi. Informacje uzyskane dzięki tym 2 metodom zostaną wykorzystane do podzielenia dokumentacji jednostronicowej na kilka stron. Cały pakiet można następnie połączyć i odwoływać się do niego w Markdownzie. W efekcie będzie ona lepiej uporządkowana, co ułatwi nawigację i zrozumienie.
Motywacja Mimo tego, że od dłuższego czasu używam oprogramowania typu open source, moja znajomość tego terminu jest dość nowa, podobnie jak moja wiedza o oprogramowaniu Linting. Gdy zaczęłam uczyć się Pythona (przez edX), zachęcałam do myślenia, jak drobne błędy mogą zepsuć cały kod. Pomyślałem, że dobrze byłoby przetestować kody i wykazać błędy. Wtedy dowiedziałem się o terminie „linting”. Nie korzystałem jeszcze z oprogramowania do lintingu, ale jestem pewien, że ułatwi mi to życie w przyszłości.
Mam wykształcenie z inżynierii elektrycznej i nieco doświadczenia w programowaniu, więc lepiej rozumiem problemy związane z kodowaniem i wymagania programistów. Poza tym mam tytuł magistra na kierunku komunikacja techniczna i zawodowa, co czyni mnie rzecznikiem użytkowników i osobą, która stara się ułatwiać im życie. Moje umiejętności i wiedza będą stanowić dobre połączenie w ramach tego projektu i wzbogacą dokumentację ESLint.
Cele Nadrzędnym celem tego projektu jest zadbanie o to, aby dokumentacja na stronie konfiguracji ESLint była zrozumiała i nie przytłaczała użytkowników. Ważne jest, aby nawigacja po treściach była łatwa i nieskomplikowana. Oto najważniejsze cele projektu. – Przeprowadzenie kompleksowego audytu treści. – Utworzenie architektury informacji w celu zrozumienia przepływu informacji. – Ulepszenie architektury informacji w celu reorganizacji dokumentacji. – Zidentyfikowanie linków i odniesień między różnymi sekcjami treści. – W razie potrzeby przepisanie lub zmodyfikowanie części dokumentacji w celu spełnienia wymagań dotyczących rekonfiguracji.
– Zadbaj o elastyczność i możliwość wielokrotnego użycia treści.
Opis projektu Konfiguracja ESLint to ważna funkcja, która umożliwia dostosowanie ESLint do potrzeb użytkownika. Użytkownicy zainteresowani konfiguracją z pewnością będą chcieli poznać 1 lub 2 aspekty w danym momencie. Dlatego ważne jest, aby użytkownik został przekierowany do konkretnego tematu, który go interesuje, i w skuteczny sposób znalazł rozwiązanie. Obecna dokumentacja konfiguracji ESLint zawiera wiele przydatnych informacji, ale jest zorganizowana w sposób, który może przytłoczyć, zirytować i zdezorientować użytkowników. Jeśli np. ktoś chce dowiedzieć się więcej o korzystaniu z wtyczek innych firm w ESLint, musi przewinąć stronę w dół, do dyskusji na temat określania parsowania, środowisk i globalnych zmiennych. Taka praktyka jest męcząca dla użytkowników i może zniechęcić ich do odwiedzenia witryny. Podobnie, jeśli użytkownik znajduje się w środku strony i chce przejść do konkretnej sekcji lub po prostu zobaczyć podobne tematy, nie będzie to dla niego łatwe, ponieważ nie ma żadnych takich pomocy. Te problemy wymagają natychmiastowej uwagi, ponieważ jakość dokumentacji, niezależnie od tego, jak dobrze została ona sformułowana, zależy od jej przydatności. W dalszej części dyskusji proponuję rozwiązania tych i innych powiązanych problemów.
Kontrola treści Pierwszym krokiem w procesie reorganizacji dokumentacji konfiguracji było przeprowadzenie kompleksowej kontroli treści. Celem audytu jest zidentyfikowanie kluczowych problemów, takich jak nieaktualne treści, duplikaty, brakujące treści itp. Utworzona w jego wyniku arkusz recenzji treści zostanie udostępniony zespołom zarządzania i dokumentacji, aby mogli się wypowiedzieć na jego temat. Pomoże to w opracowaniu nowej strategii porządkowania i prezentowania dokumentacji.
Tworzenie architektury informacji Stworzenie architektury informacji (IA) może okazać się przydatne, aby zrozumieć sieć wiedzy lub przepływ informacji w dokumentacji konfiguracji. Wyniki audytu treści posłużą za dobrą podstawę do zrozumienia i rozwoju przepływu informacji. Zostanie utworzona ulepszona wersja IA, która ułatwi uporządkowanie i zaprezentowanie dokumentacji w lepszy sposób. Ulepszona AI nie tylko zrestrukturyzuje obecne treści, ale także wykryje linki i odgałęzienia między różnymi sekcjami dokumentacji, tworząc w ten sposób wydajną sieć. Na przykład po zawartości sekcji „Konfigurowanie reguł” może znajdować się link „Wyłączanie reguł z wbudowanymi komentarzami”. Można też zidentyfikować inne takie linki, co pozwala tworzyć relacje między różnymi sekcjami dokumentacji.
Spis treści Audyt treści i IA zapewnią odpowiednie informacje do utworzenia szczegółowego spisu treści z linkami do konkretnych sekcji i pod-sekcji dokumentacji. Utworzenie osobnych plików dla każdej sekcji i dodanie odpowiednich odwołań do innych sekcji może zwiększyć wartość całego zestawu dokumentów. Można utworzyć spis treści dla użytkowników, którzy mają dostęp do dokumentacji konfiguracji, aby ułatwić im korzystanie z witryny. Spis treści może zawierać wszystkie nagłówki pierwszego i drugiego poziomu, aby był zwięzły i wyczerpujący. Jedną z takich metod jest na przykład używanie usługi Prettier (https://prettier.io/docs/pl/index.html) do porządkowania dokumentacji.
Cała dokumentacja zostanie utworzona w formacie Markdown, aby była prosta i dobrze zorganizowana. Dołożymy wszelkich starań, aby dokumentacja była wielokrotnego użytku, ponieważ może się ona rozrastać i zmieniać w przyszłości.
Narzędzia do wykorzystania Niektóre ważne narzędzia, które mogą się przydać podczas pracy nad projektem: - Draw.io do tworzenia ilustracji dla IA w razie potrzeby - Atom (lub podobny edytor) do pisania i edytowania dokumentów w Markdown
– GitHub, aby zapewnić kontrolę wersji dokumentacji.
Etapy projektu Od momentu przesłania propozycji do ukończenia projektu, te wstępne etapy zapewnią, że projekt zostanie ukończony na czas, zachowując odpowiednią kolejność.
10 lipca 2020 r. – 16 sierpnia 2020 r.: sprawdzenie i wybór propozycji. Przeczytam dokumentację ESLint i zdobędę umiejętności potrzebne do zrealizowania projektu (np. pisanie w Markdownzie, współpraca w GitHub). Będę też współtworzyć dokumentację na GitHubie i współpracować z innymi osobami, aby lepiej ją zrozumieć.
17 sierpnia 2020 r. – 13 września 2020 r.: integracja z lokalną społecznością. W tym czasie będę ulepszać swoją propozycję na podstawie rozmów z mentorami i odpowiednimi zespołami. W razie potrzeby edytuję też cele i kamienie milowe. Sporządzę też listę narzędzi, które posłużą do realizacji projektu.
14–19 września 2020 r.: audyt treści: na początek przeprowadzę kompleksowy audyt treści dokumentacji konfiguracji. Celem jest zwrócenie uwagi na problemy związane z treścią i jej prezentacją.
20–25 września 2020 r.: architektura informacji (AI) Po sprawdzeniu treści utworzymy architekturę informacji dokumentacji konfiguracji. Skupię się na przedstawieniu sieci wiedzy w zrozumiały sposób. Pomoże to poprawić przepływ informacji.
26–30 września 2020 r.: linki i odwołania W tym czasie będę analizować interfejs API, aby zmapować linki i odwołania między różnymi sekcjami dokumentacji. Utworzę również hierarchię wszystkich sekcji, aby usprawnić działanie IA.
1–3 października 2020 r.: ostateczna mapa Na podstawie informacji uzyskanych dzięki audytowi treści i IA stworzę ostateczną mapę, która zostanie zaimplementowana w przeorganizowanej dokumentacji konfiguracji. Ta obszerna mapa będzie zawierać spis treści, hierarchię tematów oraz listę linków i odnośników między sekcjami dokumentacji.
4–5 października 2020 r.: dyskusja W tym momencie, czyli przed edycją dokumentacji, przedstawię moje odkrycia i plan mentorom oraz odpowiednim zespołom. Ich opinia pomoże nam ulepszyć plan i wprowadzić ewentualne zmiany.
6–20 października 2020 r.: przepisywanie i edytowanie W tym czasie będę edytować i aktualizować sekcje dokumentów, które wymagają poprawek. Niektóre sekcje dokumentacji konfiguracji mogą zostać przeredagowane lub można było dodać do niej nowe elementy. Na tym etapie należy zadbać o to, aby dokumentacja była dokładna, aktualna, elastyczna i można było jej używać wielokrotnie.
21–25 października 2020 r.: poprawki i linki W tym okresie będę sprawdzać swoją pracę, aby pozbyć się błędów gramatycznych i strukturalnych oraz sprawdzić poprawność swoich prac. Dodam też linki i odniesienia między sekcjami zgodnie z architekturą informacji, aby mieć pewność, że dokumentacja jest zgodna z wcześniej opracowaną mapą wiedzy.
26–31 października 2020 r.: od 26 października 2020 r. do przesyłania zgłoszeń Połączę wszystkie pliki Markdown, utworzę spis treści i udostępnię wersje robocze mentorom. Na podstawie tych informacji prześlesz pierwszą wersję roboczą w formie kompletnego pakietu.
1–5 listopada 2020 r.: pierwsza korekta Uzyskam ich opinię i omówię z nimi swoje pomysły, aby stworzyć listę zmian, które należy wprowadzić.
6–12 listopada 2020 r.: pierwsze poprawki Z pomocą opinii mentorów poprawię pierwszą wersję dokumentacji. Dokładne zmiany będą zależeć od charakteru komentarzy i opinii, ale celem fazy edycji będzie ponowne wykorzystanie, dokładność i elastyczność.
13–15 listopada 2020 roku: druga weryfikacja Po zakończeniu wprowadzania wstępnych zmian po raz kolejny omówię postępy z moimi mentorami i odpowiednimi zespołami. Te dyskusje będą dotyczyć zmian wprowadzonych w pierwszej wersji oraz innych problemów, które mogą pojawić się w trakcie edycji.
16–19 listopada 2020 r.: druga edycja. Następnie przez 4 dni będę edytować dokument. Otrzymane w ten sposób wersje zostaną omówione z mentorami, aby nadać im ostateczny kształt. Po zakończeniu tej fazy dokumenty będą w końcowej formie i gotowe do przesłania na stronę internetową oraz do repozytorium GitHub.
20–23 listopada 2020 r.: przesyłanie na stronie internetowej: po wprowadzeniu wszystkich niezbędnych poprawek dokumenty zostaną przesłane na stronę internetową. Będziemy odpowiednio rozwiązywać wszystkie problemy napotkane podczas tego procesu, ponieważ na przygotowanie dokumentacji jeszcze pozostało kilka dni.
24–28 listopada 2020 r.: raport z projektu W tym 5-dniowym okresie zostanie utworzony szczegółowy raport z projektu. Cele, problemy, wyzwania i proponowane rozwiązania będą częścią raportu z projektu. Raport zostanie udostępniony mentorom, którzy przekażą swoje opinie.
29–30 listopada 2020 r.: ostatnie przesłanie projektu Twój projekt wraz ze wszystkimi plikami oraz raportem zostanie przekazany mentorom. Cały projekt zostanie sprawdzony podczas spotkania lub dyskusji z mentorami i odpowiednimi zespołami.
W trakcie projektu będę konsultować się z mentorami, aby uzyskać ich cenne opinie. Wszystkie te kamienie milowe można zmienić na podstawie rozmów z mentorami w okresach budowania relacji w społeczności i sprawdzania ofert.
Informacje o mnie Posiadam tytuł licencjata z inżynierii elektrycznej i tytuł magistra z komunikacji technicznej i zawodowej uzyskane na Uniwersytecie Stanowym w Północnej Karolinie. Mam doświadczenie w pisaniu i redagowaniu tekstów technicznych i profesjonalnych, zarządzaniu komunikacją i treściami, badaniach użyteczności stron internetowych i urządzeń mobilnych oraz projektowaniu instrukcji. Pracowałem jako zastępca redaktora w publikacji online (Global Village Space) i jako stażysta ds. komunikacji w Duke Forge na Uniwersytecie Duke. Interesuje mnie też kreatywne pisanie.