Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- gRPC-Brama
- Pisarz techniczny:
- Iamrajiv
- Nazwa projektu:
- Refaktoryzacja istniejącej witryny z Dokumentami gRPC-Gateway
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Streszczenie:
Witryna z dokumentami dla użytkowników została zaprojektowana tak, aby ułatwić użytkownikom korzystanie z produktów lub usług. Dobra witryna z dokumentami dla użytkowników jest bardzo ważna, ponieważ pozwala użytkownikom nauczyć się korzystać z oprogramowania, jego funkcji, porad i wskazówek, a także rozwiązywać typowe problemy związane z używaniem oprogramowania. Zmniejsza też koszty pomocy i jest częścią tożsamości firmy. Dobra witryna z dokumentami dla użytkowników jest oznaką prawidłowego działania usługi – zespołu programistów. Bez odpowiedniej witryny z dokumentami dla użytkowników użytkownik może nie wiedzieć, jak wykonywać powyższe czynności w sposób skuteczny i wydajny. Witryna z dokumentami dla użytkowników może odgrywać kluczową rolę w sukcesie usługi, ponieważ wspaniała komunikacja jest podstawą każdej firmy i produktu, a doskonała dokumentacja opiera się na takiej komunikacji i umieszcza ją w łatwym do zarządzania układem, do którego każdy może odnieść sukces.
W chwili tworzenia tego repozytorium gRPC-Gateway zostało rozwidlone około 1200 razy, a przesłane przez nie 184 osoby przyczyniły się do tego, co pokazuje, że wiele osób na całym świecie korzysta z gRPC-Gateway i może chcieć zapoznać się z jej dokumentacją użytkownika, aby uzyskać wskazówki na temat korzystania z gRPC-Gateway. Dokumentacja użytkownika i witryna z dokumentacją gRPC-Gateway są jednak obecnie nieaktualne i niepełne, a społeczność gRPC-Gateway chce wykorzystać ten projekt do refaktoryzacji istniejącej witryny z Dokumentami i ulepszyć witrynę z dokumentacją, aby użytkownicy mogli bezproblemowo korzystać z gRPC-Gateway.
OBECNY STAN:
Obecnie w witrynie z dokumentacją gRPC-Gateway występują dwa główne problemy:
• Pierwszy problem polega na tym, że witryna z Dokumentami jest nieaktualna. Styl i struktura użytej witryny oraz motywu są przestarzałe, niekompletne, trudne w nawigacji lub znajdowane informacje, nie obejmują wielu funkcji dobrej witryny z Dokumentami. refaktoryzacja istniejącej witryny Dokumentów w gRPC-Gateway będzie polegała na zmianie stylu witryny, dodaniu funkcji takich jak wyszukiwanie dokumentów itp., ulepszeniu jej interfejsu, uporządkowaniu samouczków i przykładów na odpowiednim pasku bocznym oraz zaktualizowania istniejących schematów blokowych i obrazów przez zaprojektowanie nowego itp. Będzie to mój główny cel, a moja praca będzie się opierać w większym stopniu na stylizowaniu i restrukturyzacji istniejącej witryny Dokumentów.
• Drugi problem polega na refaktoryzacji istniejącej dokumentacji, samouczków i przykładów itp. gRPC-Gateway. Można to zrobić, usuwając literówki i błędy gramatyczne w plikach, poprawiając ich dopasowanie we fragmentach kodu Go i refaktoryzując fragmenty w języku Go zgodnie z formatami Gofmt. W razie potrzeby możemy dodać więcej dokumentacji, samouczków i przykładów lub wykorzystać istniejące pliki po refaktoryzacji. Jest to mój drugorzędny cel i zrobię to po osiągnięciu głównego celu, tj. określenia stylu i przeredagowania struktury istniejącej witryny z dokumentami.
DLACZEGO PROPONOWANE DOKUMENTY WYDARZENIA POWIADOMIENIA STANOWIĄ WSPIERAJĄCĄ WSZYSTKO W SIECI OBECNEJ?
Opracowana będzie struktura witryny z dokumentami dla użytkowników w celu poprawy jej wydajności, spójności i spokoju ducha. Aplikacja uzyska lepszy wygląd i interfejs z odpowiednio stylizowanymi sekcjami, a funkcje będą zawierać pisemne przewodniki oraz powiązane z nimi schematy blokowe i obrazy.
Dokumentacja gRPC-Gateway zawiera dobry opis metody i przykładu. Nadal jednak korzysta ze starego motywu Jekyll, a z czasów współczesnych mamy lepsze motywy SSG (Static Site Generator) Jekyll. Trzeba też zmienić strukturę stron i sprawić, by były bardziej przydatne dla użytkowników, dodając nowe przykłady i samouczki oraz aktualizując i przeredagowując poprzednie treści.
STRUKTURA I PLAN DZIAŁANIA PROPONOWYCH CELU I POMYSŁÓW:
GŁÓWNY CEL TEGO PROJEKTU:
Powyższe cele i pomysły można zrealizować w następujący sposób:
Zmieniamy bieżący motyw Jekyll na bardziej intensywny motyw. Powodem, dla którego warto ponownie użyć motywów Jekyll, jest to, że obsługa projektu powinna być łatwa w użyciu i łatwy w obsłudze, ponieważ znają oni już strukturę i motyw Jekyll, które są podobne do nowego motywu Jekyll.
Po przejrzeniu różnych motywów Jekyll w internecie udało mi się znaleźć ten https://idratherbewriting.com/document-theme-jekyll/ pakiet motywów, który najlepiej pasuje do witryny z dokumentami gRPC-Gateway ze względu na tę funkcję:
• Markdown: Aby pisarze ds. technicznych nie musieli się martwić o instalację. Mogą po prostu zapisywać informacje w pliku .md. Każdy może kliknąć przycisk edycji widoczny w witrynie (nowa funkcja) i wprowadzić zmiany na stronie w GitHubie (edytować lub sugerować zmiany). Dzięki temu użytkownicy będą mogli dodawać nowe treści lub edytować istniejące.
• 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 udostępniania swoich opinii na temat postów i samouczków. Może odczytywać dokumenty innych osób w dokumentacji projektu.
• Nowe informacje o wersji i blogi: – Witryna powinna być aktualizowana o nowe posty na blogu i aktualności dotyczące bieżącego rozwoju i planu rozwoju. Na stronie docelowej powinno się znaleźć takie logo.
• Szybkie tworzenie: Większość platform SSG (Static Site Generator) działa na serwerze, a zmiany w pliku są natychmiast odzwierciedlane w interfejsie użytkownika. Proces wdrażania i kompilacji również powinien być prosty. Jeśli w przyszłości będziemy chcieli zmienić zasady, użyjemy tego narzędzia. Potem nie powinno być problemu. Większość platform obsługuje pisanie w formacie Markdown, więc wystarczy przenieść pliki .md i niewiele zmian powinno wystarczyć.
Podzielę istniejące strony witryny na nowe sekcje i strony :
• Strona docelowa:-
Strona docelowa powinna wskazywać główne funkcje gRPC-Gateway.
- Wprowadzenie do gRPC-Gateway (przekierowanie do przewodnika użytkownika)
- Prosta instrukcja instalacji (krótkie polecenia)
- Dlaczego warto używać gRPC-Gateway
- Projekt korzystający z gRPC-Gateway
Dlatego nie musisz wpisywać długiego opisu. Wystarczy, że podasz główne punkty na stronie docelowej i podaj link, który prowadzi do szczegółowych informacji.
• Strona przewodnika użytkownika gRPC-Gateway:
- Instrukcja instalacji.
- Krótkie wprowadzenie do gRPC-Gateway.
• gRPC-Gateway – strona z przewodnikiem dla programistów:
Przewodnik dla programistów, Przewodnik dotyczący udostępniania treści, konfiguracja Git, Kodeks postępowania, Konfiguracja dokumentacji, przepływ pracy deweloperski itd. prowadzą do podobnych stron. Potrzebna jest więc refaktoryzacja i zmiana kolejności wszystkich plików. Główna strona programistyczna powinna zawierać wszystkie te strony, a hiperlink zostanie utworzony na każdym etapie.
• Informacje o stronie bramy gRPC:-
Lista wszystkich współtwórców powinna być widoczna w sekcjach zespołu. Szybkie linki i informacje o wersjach zostaną dodane, aby użytkownik mógł zapoznać się z aktualnymi wiadomościami dotyczącymi gRPC-Gateway.
• Strona z blogami, informacjami o wersji i samouczkami:
Uważam, że witryna powinna mieć opcję blogowania. Dzięki temu można łatwo przedstawiać wiadomości i materiały. Strona samouczka zawiera kilka popularnych prelekcji i artykułów, w których wyjaśniamy pojęcia interfejsów API gRPC-Gateway. Współtwórcy mogą dodawać linki do samouczka na stronie samouczka.
Po wykonaniu powyższego zadania zaktualizuj te same zmiany w gałęzi wersji 2 i wprowadź jednakowe zmiany w gałęzi głównej gRPC-Gateway.
DODATKOWY CEL TEGO PROJEKTU:
Należy wprowadzić inne zmiany, aby dokumentacja gRPC-Gateway była bardziej dokładna i czytelna:
• Poprawianie błędów gramatycznych i typograficznych oraz porządkowanie i dopasowywanie linków oraz postów w witrynie we wszystkich istniejących plikach gRPC-Gateway.
• W razie potrzeby dodawanie większej ilości dokumentacji i treści w gRPC-Gateway, ponieważ większość funkcji ma bardzo krótką dokumentację, np. w sekcji Dokumentacja na stronie AWS, Background and Usage itp.
• Refaktoryzacja fragmentów kodu Go gRPC-Gateway zgodnie z formatami Gofmt
Po wykonaniu powyższego zadania zaktualizuj te same zmiany w gałęzi wersji 2 i wprowadź jednakowe zmiany w 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 potrafię używać dowolnego systemu kontroli wersji, więc wykonywanie poleceń na GitHubie nie będzie problemem. • Co więcej, motywuje mnie do pracy nad projektami, które są wartościowe dla ludzi. Uważam, że jeśli chcesz, by ktoś zrobił coś w najefektywniejszy sposób, musisz to udokumentować. Dokumentując swoje procesy, zapewniasz wydajność, spójność i spokój ducha dla wszystkich zaangażowanych osób. • Znam przepływ pracy i bazę kodu gRPC-Gateway, ponieważ od 2 miesięcy współpracuję nad gRPC-Gateway i zostało scalonych 11 wyników PR.