Ta strona zawiera szczegółowe informacje na temat projektu dotyczącego pisania technicznego zaakceptowanego do udziału w sezonie Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- ESLint
- Pisarz techniczny:
- Chawar
- Nazwa projektu:
- Uporządkuj i napisz na nowo dokumentację konfiguracji
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
W skrócie
Celem tego projektu jest zmiana struktury dokumentacji konfiguracji ESLint i stworzenie efektywnej architektury informacyjnej. Ułatwi to poruszanie się po witrynie, a także jej użyteczność i użyteczność.
Podsumowanie projektu Dokumentacja konfiguracji usługi ESLint (https://eslint.org/docs/user-guide/configuring) w obecnym stanie zawiera wiele informacji na jednej stronie. Pomimo dużej liczby nagłówków, podtytułów i odpowiednich akapitów na stronie dokumentacja może być przytłaczająca. Nie ma możliwości przejścia do konkretnej sekcji strony, co byłoby frustrujące dla użytkownika zainteresowanego tą sekcją. Informacje z powodu braku organizacji również mogą zostać utracone, nie będą spełniały swoich funkcji i nie będą wymagały od użytkowników dodatkowego wysiłku.
Te problemy można jednak rozwiązać, wykonując kilka czynności. Proponuję audyt treści w ramach pierwszego etapu reorganizacji. Audyt treści pomoże nie tylko zidentyfikować problemy związane z prezentacją informacji, ale także ujawnić jej wady (np. nieaktualne lub niepełne informacje). Następnie planuję utworzyć architekturę informacji (IA), aby ujawnić sieć wiedzy. Dzięki temu będziemy mogli grupować informacje według różnych tematów i wyszukiwać powiązania między różnymi tematami ściśle ze sobą powiązanymi. Informacje uzyskane w ramach tych 2 metod posłużą następnie do podziału jednostronicowej dokumentacji na wiele stron. Cały pakiet będzie można połączyć i wykorzystać w formacie Markdown. W rezultacie powstaje lepiej uporządkowana wersja dokumentacji konfiguracji, łatwiejsza w obsłudze i zrozumiała.
Motywacja Mimo że od jakiegoś czasu używam oprogramowania open source, moja znajomość tego terminu jest dość nowa, podobnie jak ja z oprogramowaniem Linting. Gdy zacząłem uczyć się Pythona (poprzez edX), zastanawiałem się, jak małe błędy mogą zepsuć cały kod. Pomyślałem, że dobrze byłoby przetestować Twoje kody i wykryć błędy. I wtedy poznałem termin „lintowania”. Jeszcze nie używam oprogramowania lintacyjnego, ale mam nadzieję, że w przyszłości znacznie ułatwi mi to życie.
Dzięki wykształceniu w dziedzinie elektrotechniki i doświadczenia w programowaniu lepiej rozumiem problemy z kodowaniem i wymagania programistów. Poza tym dyplom w dziedzinie komunikacji technicznej i komunikacji zawodowej sprawia, że jestem adwokatem użytkowników i próbuję ułatwić im życie. Moje umiejętności i wiedza będą przydatne w tym projekcie, wzbogacając dokumentację ESLint.
Cele Nadrzędnym celem tego projektu jest zadbanie o to, aby dokumentacja na stronie konfiguracji ESLint była łatwa do zrozumienia i nie przytłaczała użytkowników. Dla powodzenia projektu ważne jest, aby poruszanie się po treści było proste i wolne od wszelkich komplikacji. Oto najważniejsze cele projektu. – Przeprowadzenie kompleksowego audytu treści – Utworzenie architektury informacji w celu zrozumienia przepływu informacji – Ulepszenie architektury informacji w celu uporządkowania dokumentacji – Identyfikacja linków i odwołań między różnymi sekcjami treści – Przeredagowanie/edytowanie fragmentów dokumentacji w razie potrzeby, aby spełnić wymagania związane ze zmianą konfiguracji
– Upewnij się, że treść jest elastyczna i nadaje się do wielokrotnego użytku
Opis projektu Konfiguracja ESLint to ważna funkcja, dzięki której ESLint można dostosować. Użytkownicy zainteresowani konfiguracją na pewno będą zainteresowani jednym lub dwoma aspektami naraz. Dlatego ważne jest, aby użytkownik został przekierowany na konkretny temat, który go interesuje, co pozwoli mu znaleźć skuteczne rozwiązanie. Obecna dokumentacja konfiguracji ESLint zawiera wiele przydatnych informacji, ale jest ona zorganizowana w taki sposób, że użytkownicy czują się przytłoczeni, frustrowani i zagubieni. Jeśli na przykład ktoś chce dowiedzieć się więcej o korzystaniu z wtyczek innych firm w ESLint, musi przewinąć w dół, aby zapoznać się z informacjami na temat określania parsera, środowisk i globalnych segmentów. Takie działanie zniechęca użytkowników i może zniechęcić ich do korzystania z witryny. Podobnie jeśli użytkownik znajduje się w środku strony i chce przejść do konkretnej sekcji lub po prostu obejrzeć podobne tematy, nie będzie to łatwe zadanie, ponieważ użytkownicy nie będą mieli takiej pomocy. Kwestie te wymagają natychmiastowej uwagi, ponieważ jakość dokumentacji, niezależnie od tego, jak dobrze została opracowana, zależy od jej przydatności. Proponuję rozwiązania tych i innych problemów, które przedstawię poniżej.
Audyt treści Pierwszym krokiem w procesie reorganizacji dokumentacji dotyczącej konfiguracji jest przeprowadzenie kompleksowej kontroli treści. Audyt ma na celu wykrycie niektórych kluczowych problemów, takich jak nieaktualne treści, powielone czy brakujące treści. Arkusz kontroli treści utworzony na podstawie wyników zostanie udostępniony zespołom zarządzającym i zespołom ds. dokumentacji w celu uzyskania ich opinii. Pomoże to w opracowaniu nowej strategii tworzenia struktury i prezentacji dokumentacji.
Tworzenie architektury informacji Aby zrozumieć sieć wiedzy lub przepływ informacji w dokumentacji konfiguracji, warto utworzyć architekturę informacji. Wyniki audytu treści będą dobrym podstawą do zrozumienia i rozwoju przepływu informacji. Zostanie wtedy utworzona ulepszona wersja analizy informacji, która pozwoli lepiej uporządkować i przedstawić dokumentację. Ta ulepszona architektura informacji nie tylko zmieni strukturę bieżącej treści, ale także zidentyfikuje linki i rozwidlenia między różnymi sekcjami dokumentacji, w ten sposób tworząc wydajną sieć. Na przykład po treści w sekcji „Konfigurowanie reguł” może prowadzić link „Wyłączanie reguł z komentarzami w tekście”. Takie linki można też zidentyfikować, tworząc relacje między różnymi sekcjami w dokumentacji.
Audyt spisu treści i strona IA zawierają informacje wystarczające do utworzenia szczegółowego spisu treści z linkami prowadzącymi do określonych sekcji i podsekcji dokumentacji. Utworzenie oddzielnych plików dla każdej sekcji i dodanie odpowiednich odwołań do innych sekcji może wzbogacić cały zestaw dokumentów. Możesz utworzyć spis treści dla użytkowników, którzy przejdą do dokumentacji konfiguracji, i ułatwi im poruszanie się po witrynie. Spis treści może zawierać wszystkie nagłówki pierwszego i drugiego poziomu, aby był zwięzły, ale wyczerpujący. Jedną z takich metod jest korzystanie z usługi Prettier (https://prettier.io/docs/en/index.html) do porządkowania dokumentacji.
Cała dokumentacja zostanie utworzona przy użyciu formatu Markdown, aby utrzymać porządek i prostszą organizację. Dołożymy wszelkich starań, aby dokumentacja nadawała się do wielokrotnego użytku, ponieważ może się powiększyć i zmienić w przyszłości.
Narzędzia do wykorzystania Kilka ważnych narzędzi, które mogą okazać się przydatne podczas pracy nad projektem, to: – Draw.io do tworzenia ilustracji dla IA w razie potrzeby – Atom (lub podobnego edytora) do pisania i edytowania dokumentów w Markdownie
- GitHub zapewniający kontrolę wersji dokumentacji
Etapy Od przesłania oferty do ukończenia projektu – zgodnie z poniższymi wstępnymi etapami projekt zostanie ukończony w odpowiednim czasie i utrzyma właściwy przebieg procesu.
10 lipca – 16 sierpnia 2020 r.: weryfikacja i wybór oferty Będę też pracować nad dokumentacją przez GitHuba i kontaktować się z innymi osobami, aby lepiej ją zrozumieć.
17 sierpnia 2020 r. – 13 września 2020 r.: więzi ze społecznością W okresie nawiązywania więzi ze społecznością dopracuję swoją propozycję na podstawie rozmów z mentorami i zainteresowanymi zespołami. W razie potrzeby wprowadzę też zmiany w celach i etapach milowych. Przygotuję także listę narzędzi, które będą używane podczas pracy nad projektem.
14 września 2020 r. – 19 września 2020 r.: kontrola treści Na początek przeprowadzę kompleksową kontrolę treści dokumentacji konfiguracji. Celem jest wskazanie problemów z treścią i jej prezentacją.
20 września 2020 r. – 25 września 2020 r.: architektura informacji Po zakończeniu kontroli treści utworzę IA z dokumentacją konfiguracji. Postaram się zaprezentować sieć wiedzy w zrozumiały sposób. Pomoże to w usprawnieniu przepływu informacji.
26 września – 30 września 2020 r.: linki i materiały referencyjne na tym etapie przeanalizuję IA, aby znaleźć linki i odniesienia między różnymi sekcjami dokumentacji. Utworzę także hierarchię wszystkich sekcji, aby w ten sposób ulepszyć IA.
Od 1 października 2020 r. do 3 października 2020 r.: ostateczna wersja mapy. Korzystając z informacji uzyskanych dzięki kontroli treści i narzędziu IA, utworzę ostateczną mapę do wdrożenia w przeredagowanej dokumentacji konfiguracji. Ta kompleksowa mapa będzie zawierać spis treści, hierarchię tematów oraz listę linków i odniesień między sekcjami dokumentacji.
Dyskusja od 4 października 2020 r. do 5 października 2020 r. Na tym etapie, przed wprowadzeniem zmian w dokumentacji, przedstawię swoje wnioski i plany mentorom i zaangażowanym zespołom. Ich opinia pomoże nam ulepszyć plan i w razie potrzeby wprowadzić w nim zmiany.
6 października 2020 r. – 20 października 2020 r.: przepisywanie i edytowanie W tym okresie będę edytować i aktualizować sekcje dokumentów tam, gdzie będą potrzebne prace. Niektóre sekcje dokumentacji konfiguracji mogą zostać napisane od nowa lub dodane do niej nowe rzeczy. Na tym etapie skupimy się na zapewnieniu, że dokumentacja jest dokładna, zaktualizowana, elastyczna i dostępna do wielokrotnego użytku.
Od 21 października 2020 r. do 25 października 2020 r.: Poprawki i linki Na tym etapie skontroluję swoje własne prace, aby pozbyć się błędów gramatycznych i strukturalnych, a także ponownie sprawdzić poprawność swojej pracy. Dodaję też linki i odniesienia między sekcjami, zgodnie z informacjami zawartymi w IA, aby mieć pewność, że dokumentacja jest zgodna z opracowaną wcześniej mapą wiedzy.
Od 26 października 2020 r. do 31 października 2020 r.: ostateczna wersja na przesłanie projektu Utworzę link do wszystkich plików Markdown, utworzę spis treści i udostępnię wersje robocze mentorom. Spowoduje to przesłanie pierwszej wersji roboczej w formie pełnego pakietu.
1 listopada 2020 r. – 5 listopada 2020 r.: pierwsza weryfikacja W ciągu tych 5 dni razem z mentorami omówię pierwszą wersję roboczą. Otrzymam ich opinie i przedstawię z nimi moje pomysły, aby utworzyć listę poprawek, które należy wprowadzić.
6 listopada 2020 r. – 12 listopada 2020 r.: Pierwsze zmiany Dzięki opiniom mentorów zmodyfikuję pierwszą wersję roboczą dokumentacji. Rzeczywiste zmiany będą zależały od charakteru komentarzy i opinii, ale celem fazy edycji będzie ponowne wykorzystanie, dokładność i elastyczność.
13 listopada 2020 r. – 15 listopada 2020 r.: druga weryfikacja Po zakończeniu wstępnych edycji jeszcze raz omówię postępy z mentorami i zespołami, których dotyczy problem. Koncentrują się one na zmianach wprowadzonych w pierwszej wersji i podkreślają wszelkie inne problemy, które mogły pojawić się w trakcie edytowania.
16 listopada 2020 r. – 19 listopada 2020 r.: drugie zmiany Następnie przeznaczę 4 dni na edytowanie dokumentu. Wersje utworzone na podstawie wyników są omawiane z mentorami, by nadać im ostateczny kształt. Po zakończeniu tego etapu dokumenty będą gotowe do przesłania na stronę internetową i do repozytorium GitHub.
20 listopada 2020 r. – 23 listopada 2020 r.: przesyłanie plików na stronę internetową Po wprowadzeniu wszystkich niezbędnych zmian dokumenty zostaną przesłane do witryny. Wszystkie problemy, które pojawią się w trakcie tego procesu, zostaną odpowiednio rozpatrzone, ponieważ będziemy mieli jeszcze kilka dni na opracowanie dokumentacji.
24 listopada 2020 r. – 28 listopada 2020 r.: raport z projektu W tym 5-dniowym okresie zostanie utworzony szczegółowy raport na temat projektu. Cele, problemy, problemy i przedstawione rozwiązania staną się częścią raportu z projektu. Raport zostanie udostępniony mentorom na potrzeby opinii.
29 listopada 2020 r. – 30 listopada 2020 r.: zgłoszenie końcowe Projekt wraz ze wszystkimi plikami i raportem z projektu zostaną przekazane mentorom. Ocena całego projektu zostanie przeprowadzona na spotkaniu/dyskusji z mentorkami i zaangażowanymi zespołami.
Przez cały czas trwania projektu będę konsultować się z mentorami, aby uzyskać ich cenne opinie. Wszystkie te etapy można zmieniać na podstawie dyskusji z mentorami w trakcie budowania społeczności i sprawdzania ofert.
O mnie Mam tytuł licencjata w dziedzinie elektrotechniki i komunikacji zawodowej na Uniwersytecie Stanowym Karoliny Północnej. Mam doświadczenie w technicznych i profesjonalnych redagowaniu tekstu, pisaniu, zarządzaniu komunikacją i zarządzaniu treścią, badaniach nad obsługą na urządzeniach mobilnych i w internecie oraz w projektowaniu instrukcji. Pracowałem jako podwykonawca w publikacji online (Global Village Space) oraz jako stażysta ds. komunikacji w Duke Forge na Duke University. Poza tym interesuję się też pisaniem kreatywnym.