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:
- GRPC
- Specjalista ds. technicznych:
- iamrajiv
- Nazwa projektu:
- Refaktoryzacja istniejącej witryny Dokumentów w gRPC-Gateway
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
STRESZCZENIE:
Witryna z dokumentami użytkownika została stworzona po to, aby pomagać użytkownikom w korzystaniu z produktu lub usługi. Dobra strona z dokumentacją dla użytkowników jest bardzo ważna, ponieważ umożliwia im zapoznanie się z korzystaniem z oprogramowania, jego funkcjami, poradami i sztuczkami, a także rozwiązywanie typowych problemów. Obniżają też koszty pomocy i stanowią element tożsamości firmy. Dobra strona z dokumentacją dla użytkowników to znak, że produkt i zespół deweloperów działają sprawnie. Bez dobrej strony z dokumentacją użytkownik może nie wiedzieć, jak skutecznie i efektywnie wykonywać te czynności. Strona z dokumentacją dla użytkowników może odgrywać kluczową rolę w zapewnieniu sukcesu produktu, ponieważ skuteczna komunikacja zawsze będzie podstawą każdej firmy lub produktu. Dobra dokumentacja to nic innego jak komunikacja w ramach łatwych do zarządzania struktur, do których każdy może mieć dostęp.
W momencie pisania tego tekstu repozytorium gRPC-Gateway zostało pobrane około 1200 razy, a 184 osób wniosło do niego swój wkład. Pokazuje to, że gRPC-Gateway jest używane przez wiele osób na całym świecie i że mogą one chcieć zapoznać się z dokumentacją użytkownika zawierającą wskazówki dotyczące korzystania z gRPC-Gateway. Dokumentacja i witryna z dokumentacją dotyczącą gRPC-Gateway są jednak obecnie nieaktualne i niekompletne. Społeczność gRPC-Gateway chce wykorzystać ten projekt do przekształcenia istniejącej witryny z dokumentacją, aby zapewnić użytkownikom płynne korzystanie z gRPC-Gateway.
STAN BIEŻĄCY:
Obecnie strona z dokumentacją bramy gRPC ma 2 główne problemy:
• Pierwszym problemem jest słaba i nieaktualna witryna z Dokumentami. Jej styl i struktura są nieaktualne, niekompletne, trudne w nawigowaniu lub znajdowaniu informacji, a nie obejmuje wielu funkcji dobrej strony z Dokumentami. Refaktoryzacja istniejącej witryny Dokumentów w gRPC-Gateway będzie obejmować stylizację witryny, dodanie funkcji takich jak wyszukiwanie dokumentów, ulepszenie interfejsu użytkownika witryny, uporządkowanie samouczków i przykładów na odpowiednim pasku bocznym oraz zaktualizowanie istniejących schematów i obrazów przez zaprojektowanie nowych. Będzie to moim głównym celem, a moja praca będzie polegać głównie na stylizacji i restrukturyzacji istniejącej witryny Dokumentów.
• Drugi problem to konieczność przebudowania istniejącej dokumentacji, samouczków i przykładów gRPC-Gateway. Można to zrobić, usuwając błędy typograficzne i gramatyczne w plikach, odpowiednio wyrównując fragmenty kodu Go i przebudowując je zgodnie z formatami Gofmt. W takim przypadku możemy też dodać więcej dokumentacji, samouczków i przykładów lub ponownie wykorzystać istniejące pliki po ich przerefaktoryzowaniu. To jest mój cel dodatkowy, który wykonam po zrealizowaniu głównego celu, czyli stylizacji i restrukturyzacji obecnej witryny Dokumentów.
DLACZEGO PROPONOWANA WITRYNA Z DOKUMENTAMI JEST LEPIEJSZA OD OBECNEJ?
Proponowana strona dokumentów użytkownika będzie uporządkowana w sposób zapewniający efektywność, spójność i bezpieczeństwo użytkownika. Nowy interfejs będzie lepiej wyglądał i działał, a sekcje i funkcje będą lepiej wyglądać dzięki dobrze sformatowanym sekcją i funkcjom zawierającym przewodniki w formie tekstu oraz powiązane z nimi schematy i obrazy.
Dokumentacja gRPC-Gateway zawiera dobry opis metody i przykład. Nadal jednak używa starego motywu Jekyll. Obecnie mamy lepsze motywy Jekylla dla SSG (Static Site Generator). Konieczne jest też przebudowanie stron i ulepszenie ich dla użytkowników poprzez dodanie nowych przykładów i samouczków oraz zaktualizowanie i przepisanie poprzednich treści.
STRUKTURA I PLAN DZIAŁAŃ PROPONOWANYCH CELÓW I POMYSŁÓW:
GŁÓWNY CEL TEGO PROJEKTU:
Powyższe cele i pomysły można realizować na kilka sposobów:
Przejście z obecnego motywu Jekyll na lepszy i bardziej niezawodny motyw. Ponowne użycie motywów Jekyll ma ułatwić konserwatorom pracę nad projektem i zrozumienie jego przepływu pracy, ponieważ znają już istniejący framework i motyw Jekyll, który jest podobny do nowego motywu Jekyll.
Po przejrzeniu różnych motywów Jekylla w internecie znalazłem ten https://idratherbewriting.com/documentation-theme-jekyll/, który najlepiej pasuje do strony z dokumentacją gRPC-Gateway ze względu na tę funkcję:
• Markdown:- Aby autorzy dokumentacji technicznej nie musieli się martwić o instalację. Mogą pisać w pliku .md. Każdy może kliknąć przycisk edycji widoczny na stronie (nowa funkcja) i wnosić swój wkład (edytować lub sugerować zmiany na stronie w GitHub), aby ją ulepszać. Zachęci to użytkowników do dodawania nowych treści lub edytowania treści w celu ich ulepszenia.
• Przeszukiwanie dokumentacji: Użytkownik powinien mieć pole wyszukiwania, aby móc łatwo i szybko znaleźć odpowiednią treść.
• Sekcja komentarzy: użytkownik może mieć możliwość komentowania i dzielenia się swoimi poglądami na temat postów i samouczków. Mogą też czytać opinie innych osób w dokumentacji projektu.
• Uwagi do nowego wydania i blogi: Witryna powinna być aktualizowana o nowe posty na blogu i aktualności na temat bieżących rozwoju i planów rozwoju programu. Na stronie docelowej powinien się znajdować blog.
• Szybkie programowanie: Większość platform SSG (Static Site Generator) działa na serwerze, a zmiany w pliku są natychmiast odzwierciedlane w interfejsie. Proces wdrażania i tworzenia powinien być prosty. Jeśli w przyszłości chcemy zmienić ramy, użyjemy To powinno być proste. Większość frameworków obsługuje format Markdown, więc wystarczy przenieść pliki .md i wprowadzić kilka zmian.
Dzielę istniejące strony na nowe sekcje i strony :
• Strona docelowa:-
Strona docelowa powinna wskazywać najważniejsze funkcje gRPC-Gateway.
- Pierwsze kroki z gRPC-Gateway (przekierowanie do przewodnika użytkownika)
- Instrukcje prostej instalacji (krótkie polecenia)
- Dlaczego warto używać gRPC-Gateway
- Projekt używający gRPC-Gateway
Zamiast pisać długi opis, lepiej jest wyświetlić na stronie docelowej główne punkty i podać link do strony z szczegółami.
• Strona z przewodnikiem użytkownika bramy gRPC:
- Przewodnik instalacji.
- Krótkie wprowadzenie do gRPC-Gateway.
• Strona przewodnika dla deweloperów gRPC-Gateway:
Przewodnik dla programistów, Przewodnik dla autorów, Konfiguracja Gita, Kodeks postępowania, Konfiguracja dokumentacji, Proces programowania itp. odsyłają do podobnych stron. Dlatego konieczne jest przebudowanie i przearanżowanie wszystkich plików. Główna strona Rozwój powinna zawierać wszystkie te strony, a hiperlink zostanie utworzony w każdym kroku.
• Strona GRPC-Gateway:
W sekcjach zespołu powinna się znajdować lista wszystkich współtwórców. Aby zachęcić użytkownika do zapoznania się z aktualnymi wiadomościami o gRPC-Gateway, należy dodać do strony linki i notatki o wydańach oraz najnowsze wpisy na blogu.
• Blogi, informacje o wydańach i strony z samouczkami:
Uważam, że witryna powinna mieć opcję blogowania. Dzięki temu wiadomości i informacje o premierach można łatwo przekazywać. Na stronie samouczka znajdziesz popularne wykłady i artykuły, które wyjaśniają pojęcia i interfejsy API gRPC-Gateway. Użytkownicy mogą dodawać linki do samouczków na stronie samouczków.
Po wykonaniu tego zadania wprowadź te same zmiany w gałęzi v2 i gałęzi głównej gRPC-Gateway.
CEL DODATKOWY TEGO PROJEKTU:
Aby dokumentacja gRPC-Gateway była bardziej niezawodna i czytelna, należy wprowadzić inne zmiany:
• Poprawiono błędy gramatyczne i typograficzne oraz uporządkowano i zgodzono linki i posty w witrynie we wszystkich istniejących plikach gRPC-Gateway.
• Dodanie w gRPC-Gateway większej ilości dokumentacji i treści, ponieważ większość funkcji ma bardzo krótką dokumentację, np. w sekcji Dokumentacja w witrynie AWS, Informacje ogólne i Stosowanie.
• Refaktoryzacja fragmentów kodu Go w gRPC-Gateway zgodnie z formatami Gofmt
Po wykonaniu tego zadania wprowadź te same zmiany w gałęzi v2 i gałęzi głównej gRPC-Gateway.
DLACZEGO JESTEM ODPOWIEDNIĄ OSOBĄ DO TEGO PROJEKTU:
Uważam, że jestem odpowiednią osobą do tego projektu, ponieważ:
• Mam doświadczenie w ulepszaniu dokumentacji organizacji i mogę używać dowolnego systemu kontroli wersji, więc wykonywanie poleceń w GitHub nie będzie problemem. • Poza tym motywuje mnie praca nad projektami, które przynoszą ludziom korzyści. Jeśli chcesz, aby ktoś zrobił coś w jak najbardziej efektywny sposób, musisz to udokumentować. Dzięki udokumentowaniu procesów zapewnisz sobie i wszystkim zaangażowanym osobom wydajność, spójność i spokój ducha. • Znam przepływ pracy i bazę kodu gRPC-Gateway, ponieważ współpracuję z gRPC-Gateway w ciągu ostatnich 2 miesięcy i udało mi się połączyć 11 działań PR.