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:
- TheGoodDocsProject
- Pisarz techniczny:
- Loquacity
- Nazwa projektu:
- Przewodnik po architekturze informacji
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Przewodnik po planowaniu architektury informacji
Ten dokument dotyczy planowania przewodnika po architekturze informacji w ramach projektu Good Docs. Został on przygotowany w ramach edycji Google Season of Docs 2020. Opisuje on przypadki użycia proponowanego przewodnika i zarysowuje strukturę takiego przewodnika na potrzeby planowania.
Architektura informacji dotyczy sposobu organizacji treści. Obejmuje strukturę treści bez określania stylu ani użytych w niej słów. Na przykład plan interakcji z użytkownikiem uwzględnia, kim jest czytelnik, jak podchodzi do treści i w jakim środowisku czyta. Następnie należałoby zastosować odpowiednią strukturę treści, która spełni te wymagania czytelników.
W idealnym świecie dokumentacja jest tworzona, zaczynając od strategii dotyczącej treści, która wykorzystuje cele biznesowe do określenia celów dokumentacji. Strategia treści jest następnie wykorzystywana do tworzenia interfejsu API, który określa układ i strukturę dokumentacji. Następnie możesz wybrać łańcuchy narzędzi i pisać treści. W przypadku większości projektów open source strategia dotycząca treści jest tak prosta, jak „napisz dokumentację, aby ludzie wiedzieli, jak korzystać z tego projektu”. Jednak nawet ta prosta strategia wystarcza do zdefiniowania skutecznego interfejsu API.
Celem tego przewodnika jest udostępnienie uproszczonego narzędzia dla niezawodowych pisarzy do opracowania analiz integracyjnych, które wystarczy do określenia, których szablonów użyć. Powinien być na tyle prosty, aby wykonywał go zwykły człowiek po południu. Zamiast edukacji powinno być faworyzować działanie. W najlepszym przypadku w sposób zwięzły przedstawia on pojęcia, zachęca czytelnika do rozważenia ich w stosunku do jego projektu i wykorzystywania wyników do przechodzenia do kolejnych zagadnień.
W ramach tego projektu należy wprowadzić pewne zmiany w pliku README, aby czytelnicy wiedzieli, jak zacząć korzystać z projektu Good Docs i jak skutecznie korzystać z przewodnika dotyczącego interfejsu API, aby wybrać odpowiedni szablon.
Główna lista odbiorców
Wszystkich osób, które chcą korzystać z szablonów projektu Good Dokumenty Google do tworzenia dokumentacji projektu.
Przypadki użycia: ta sekcja ma na celu pomóc czytelnikom w odnalezieniu odpowiedniego przewodnika dotyczącego interfejsu API. Pomoże nam to określić strukturę Przewodnika, aby zapewnić jak największą przydatność dla tych czytelników.
Scenariusz:
Osoba pracuje nad projektem open source bez dokumentacji albo nad pakietem dokumentacji, który jest źle zorganizowany lub napisany. Decydują się użyć projektu The Good Docs do uporządkowania dokumentacji, ale nie wiedzą, od czego zacząć. Czytają plik README, aby dowiedzieć się, jak zacząć korzystać z szablonów, a potem Information Architecture Guide, aby opracować strategię dotyczącą treści i zaplanować wygląd pakietu dokumentacji.
Oferta pakietowa
Zaktualizuj README, aby dokładniej poprowadzić nowego czytelnika przez cały projekt, w tym jasne pierwsze kroki. Jednym z pierwszych kroków jest przeczytanie i odpowiedzenie na pytania w nowym przewodniku po AI. Taki przewodnik zachęca czytelnika do zastanowienia się nad odbiorcami, schematem treści, matrycami użytkowników i zadań itp., nie nakładając na niego zbyt dużego obowiązku zapoznania się z tymi zagadnieniami w akademickim sensie. Po wykonaniu tego zadania czytelnik będzie wiedzieć, jakie szablony są wymagane i jak je wypełnić.
Research
Aby poprzeć to badaniami, sięgnę po książkę Abby Covert (http://www.howtomakesenseofanymess.com/), częściowo dlatego, że znam ją bardzo dobrze i była ona podstawą wielu treści, które już napisałem i będę wykorzystywać, ale też dlatego, że osoby, które dopiero zaczynają przygodę z IA, mogą ją łatwo przeczytać, jeśli będą zainteresowane. W tym sensie jest to trochę „drzwiami do sztucznej inteligencji”.
Draft ToC
README:
-- Wprowadzenie do projektu The Good Docs |_ Kto powinien używać szablonów |_ Jak działają szablony |_ Współpraca przy projekcie -- Szablony |_ Lista wszystkich bieżących szablonów |_ Wybieranie szablonów do użycia |_ Zanim zaczniesz -- Zanim zaczniesz pisać |_ Kto czyta dokumenty? |_ Dlaczego czytają dokumenty? |_ Pisanie dla czytelników
Przewodnik po architekturze informacji:
-- Wprowadzenie |_ Co to jest IA? |_ Dlaczego to powinno mnie obchodzić? – Zidentyfikuj problem. – Określ swój cel. – Zmierz odległość. – Zastosuj strukturę. – Przygotuj się do wprowadzania zmian.