Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- ESLint
- Pisarz techniczny:
- Chawar
- Nazwa projektu:
- Uporządkuj i przepisz dokumentację konfiguracji
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
W skrócie
Celem tego projektu jest zrekonstruowanie dokumentacji konfiguracji ESLint i stworzenie efektywnej architektury informacyjnej. Ułatwi to nawigację, a także zwiększy użyteczność i użyteczność dokumentacji.
Podsumowanie projektu Dokumentacja konfiguracji narzędzia ESLint (https://eslint.org/docs/user-guide/configuring) w obecnym stanie zawiera wiele informacji na jednej stronie. Pomimo 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 może być irytujące dla użytkowników zainteresowanych daną sekcją. Informacje z powodu braku organizacji również mogą zostać utracone, nie będą odpowiadały potrzebom i nie będą spełniać wymagań użytkowników.
Można jednak rozwiązać te problemy, wykonując kilka czynności. Jako pierwszy krok w procesie reorganizacji proponuję audyt treści. Audyt treści nie tylko pomaga w identyfikowaniu problemów związanych z prezentacją informacji, ale także wskazuje masy w treściach (np. nieaktualne lub niepełne informacje). Następnie planuję utworzyć architekturę informacji (IA), aby wysunąć się na 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ązane. Wnioski uzyskane w wyniku tych 2 metod posłużą do podzielenia jednostronicowej dokumentacji na wiele stron. Cały pakiet można wtedy połączyć i odwzorować w formacie Markdown. W rezultacie powstaje lepiej uporządkowana wersja dokumentacji konfiguracji, która jest łatwiejsza w nawigacji i zrozumiała.
Motywacja Mimo że używam oprogramowania open source od jakiegoś czasu, moja znajomość tego terminu jest dosyć nowa – podobnie jak w przypadku oprogramowania Linting. Gdy zacząłem uczyć się Pythona (przez edX), zastanawiałem się, jak drobne błędy mogą zepsuć cały kod. Pomyślałem, że dobrze byłoby sprawdzić kody i wykryć błędy. Potem znam termin „lintowanie”. Jeszcze nie używałam oprogramowania lintacyjnego, ale na pewno ułatwi mi to życie w nadchodzących dniach.
Dzięki wykształceniu w zakresie inżynierii elektrycznej i doświadczenia w programowaniu mogę lepiej zrozumieć problemy związane z kodowaniem i wymagania programistów. Poza tym dyplom w dziedzinie komunikacji technicznej i komunikacji zawodowej sprawia, że jestem adwokatem użytkowników i staram się ułatwiać życie ludziom. Moje umiejętności i wiedza będą przydatne w przypadku tego projektu, wzbogacając dokumentację ESLint.
Cele Nadrzędnym celem tego projektu jest zapewnienie, że dokumentacja na stronie konfiguracji ESLint jest łatwa do zrozumienia i nie przytłacza użytkowników. Dla powodzenia projektu ważne jest, aby poruszanie się po treści było łatwe i wolne od wszelkich komplikacji. Oto najważniejsze cele projektu. – Przeprowadzenie kompleksowego audytu treści – Opracowanie architektury informacji w celu zrozumienia przepływu informacji – Ulepszenie architektury informacji w celu uporządkowania dokumentacji – Identyfikowanie linków i odwołań między różnymi sekcjami treści. – Modyfikowanie i edytowanie części dokumentacji zgodnie z wymaganiami dotyczącymi zmiany 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 można dostosować ten program. Użytkownicy zainteresowani konfiguracją na pewno będą zainteresowani jednym lub dwoma aspektami naraz. W związku z tym ważne jest, aby użytkownik został przekierowany na konkretny temat, który go interesuje, co pozwoli mu skutecznie znaleźć rozwiązanie. Obecny stan dokumentacji konfiguracji ESLint zawiera wiele przydatnych informacji, ale jest on zorganizowany w taki sposób, że użytkownicy czują się przytłoczeni, sfrustrowani 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 przeczytać artykuł o określaniu parsera, środowisk i globalnych języków. Takie działanie jest męczące dla użytkowników i może zniechęcić ich do odwiedzenia witryny. Podobnie jeśli użytkownik znajduje się pośrodku strony i chce przejść do konkretnej sekcji lub po prostu obejrzeć podobne tematy, nie będzie to dla niego łatwe zadanie, ponieważ użytkownicy nie będą mogli udzielić takiej pomocy. Kwestie takie wymagają natychmiastowej interwencji, ponieważ jakość każdej 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 zostaną omówione w dalszej dyskusji.
Audyt treści Pierwszym krokiem w procesie reorganizacji dokumentacji konfiguracji jest przeprowadzenie szczegółowej kontroli treści. Celem audytu jest wykrycie niektórych kluczowych problemów, takich jak nieaktualne treści, powielone, brakujące treści itp. Arkusz kontroli treści utworzony na jego podstawie zostanie udostępniony zespołom zarządzającym i zajmującym się dokumentacją w celu uzyskania ich opinii. Pomoże to w opracowaniu nowej strategii, w której opracujesz i uporządkujesz dokumentację.
Tworzenie architektury informacji Aby zrozumieć sieć wiedzy lub przepływ informacji w dokumentacji konfiguracji, warto utworzyć architekturę informacji. Wyniki audytu treści stanowią dobrą podstawę do zrozumienia i rozwoju przepływu informacji. Następnie zostanie utworzona ulepszona wersja IA, co pozwoli lepiej uporządkować i zaprezentować dokumentację. W ten sposób ulepszona zostanie nie tylko bieżąca treść, lecz także wskazane linki i rozwidlenia między różnymi fragmentami dokumentacji, w ten sposób tworzący wydajną sieć. Na przykład po treści z sekcji „Konfigurowanie reguł” może znajdować się link „Wyłączanie reguł z komentarzami w tekście”. Takie linki można też wykrywać, tworząc relacje między różnymi sekcjami dokumentacji.
Audyt treści i AI dostarczą odpowiednich informacji do utworzenia szczegółowego spisu treści z linkami prowadzącymi do określonych sekcji i podsekcji w dokumentacji. Utworzenie osobnych plików dla każdej sekcji i dodanie odpowiednich odwołań do innych sekcji może wzbogacić cały zbiór dokumentów. Spis treści można utworzyć dla użytkowników, którzy znajdują się na stronie z dokumentacją 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. Jednym z przykładów jest korzystanie z aplikacji Prettier (https://prettier.io/docs/en/index.html) do porządkowania dokumentacji.
Cała dokumentacja jest stworzona z wykorzystaniem Markdown, aby utrzymać porządek i łatwość. Szczególnie zadbamy o to, aby dokumentacja nadawał się do wielokrotnego użytku, ponieważ może się powiększyć i zmieniać w przyszłości.
Narzędzia, które mogą okazać się przydatne podczas pracy nad projektem: – Draw.io do tworzenia ilustracji dla IA w razie potrzeby – Atom (lub podobnego edytora) do pisania i edytowania dokumentów w Markdownie
– GitHub, aby zapewnić kontrolę wersji dokumentacji
Etapy Od przesłania oferty do ukończenia projektu dzięki tym wstępnym etapom projekt zostanie ukończony w odpowiednim terminie.
10 lipca 2020 r. – 16 sierpnia 2020 r.: ocena i wybór propozycji Przejrzę dokumentację ESLint i rozwinę umiejętności potrzebne do ukończenia projektu (np. pisanie przy użyciu Markdowna, współpraca na GitHubie). Będę też współpracować z dokumentacją przez GitHuba i kontaktować się z innymi osobami, aby lepiej ją zrozumieć.
17 sierpnia 2020 r. – 13 września 2020 roku: więzi ze społecznością W okresie nawiązywania więzi ze społecznością dopracuję propozycję na podstawie dyskusji z mentorami i zaangażowanymi zespołami. W razie potrzeby wprowadzę także zmiany w celach i kamieniach milowych. Wybiorę też narzędzia, których użyjesz do 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ę raport IA dotyczący dokumentacji konfiguracji. Postaram się przedstawić sieć wiedzy w zrozumiały sposób. Pomoże to w usprawnieniu przepływu informacji.
26 września 2020 r. – 30 września 2020 r.: linki i materiały referencyjne W tym czasie przeanalizuję informacje na temat IA, aby wyznaczyć linki i odniesienia między różnymi sekcjami dokumentacji. Utworzę również hierarchię wszystkich sekcji, co pozwoli ulepszyć IA.
Od 1 października 2020 r. do 3 października 2020 r.: ostateczna mapa Dzięki informacjom uzyskanym z kontroli treści i IA stworzę ostateczną mapę do wdrożenia w zmodyfikowanej dokumentacji konfiguracji. Taka kompleksowa mapa będzie zawierać spis treści, hierarchię tematów oraz listę linków i odniesień do poszczególnych sekcji dokumentacji.
4 października 2020 r. – 5 października 2020 r.: dyskusja Na tym etapie, przed edytowaniem dokumentacji, zaprezentuję swoje wnioski i plany mentorom i zespołom, których dotyczy problem. Ich opinie pomogą nam ulepszyć plan i w razie potrzeby wprowadzić zmiany.
Od 6 października 2020 r. do 20 października 2020 r.: przeredagowanie i edytowanie W tym czasie będę edytować i aktualizować sekcje dokumentów, jeśli są potrzebne zmiany. Niektóre sekcje dokumentacji konfiguracji mogą zostać napisane od nowa lub dodane do niej nowe informacje. Na tym etapie skupimy się na zapewnieniu, że dokumentacja jest dokładna, zaktualizowana, elastyczna i nadaje się do wielokrotnego użytku.
Od 21 października 2020 r. do 25 października 2020 r.: poprawki i linki Na tym etapie samodzielnie sprawdzę swoje prace, aby pozbyć się błędów gramatycznych i strukturalnych, a także dokładnie sprawdzić poprawność treści. Dodaję też linki i odniesienia między sekcjami, zgodnie z informacjami pochodzącymi od 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 zgłoszenia Załączę wszystkie pliki 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 wspólnie z mentorami omówię pierwszą wersję roboczą. Otrzymam ich opinie i omówię 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 wyślę pierwszą wersję roboczą dokumentacji. Rzeczywiste zmiany będą zależały od charakteru komentarzy i opinii, ale podstawą fazy edycji będą cele ponownego wykorzystania, dokładności i elastyczności.
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 odpowiednimi zespołami. 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 przeznaczym 4 dni na edytowanie dokumentu. Wersje powstające w efekcie zostaną omówione z mentorami, aby 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 dokumentów na stronie Po wprowadzeniu wszystkich niezbędnych zmian dokumenty zostaną przesłane do witryny. Wszelkie problemy napotkane w trakcie tego procesu będziemy odpowiednio rozpatrywać, ponieważ mamy jeszcze kilka dni na opracowanie dokumentacji.
24 listopada 2020 r. – 28 listopada 2020 roku: raport z projektu W tym 5-dniowym okresie zostanie utworzony szczegółowy raport na temat projektu. Cele, problemy, problemy i przedstawione rozwiązania stanowią część raportu dotyczącego projektu. Raport zostanie udostępniony mentorom na potrzeby opinii.
29 listopada 2020 r. – 30 listopada 2020 r.: zgłoszenie końcowe Projekt, wszystkie pliki i raport z projektu zostaną przekazane mentorom. Cały projekt zostanie oceniony przez spotkania/dyskusję z mentorami 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 zmienić na podstawie dyskusji z mentorami w trakcie tworzenia społeczności i sprawdzania ofert.
O mnie Mam tytuł licencjata elektrotechniki oraz dyplom z dziedziny komunikacji technicznej i komunikacji zawodowej na Uniwersytecie Stanowym Karoliny Północnej. Mam doświadczenie w dziedzinach technicznych i profesjonalnych pisania i edytowania treści, komunikacji i zarządzania treścią, badań nad obsługą stron i urządzeń mobilnych oraz projektowania instrukcji. Pracowałem jako podwykonawca publikacji online (Global Village Space) oraz jako stażysta Communications w Duke Forge na Duke University. Poza tym interesuję się też pisaniem kreatywnym.