Jak zautomatyzować przepływ dokumentacji dla programistów?

Aby jak najlepiej wykorzystać ten samouczek, powinieneś znać: Git, GitHub i Linux oraz wiersz poleceń.

Dlaczego powinieneś dbać o wysokiej jakości dokumentację?

Wiele zespołów zmaga się z pisaniem dokumentacji . Kiedy idziesz do sprawdzenia frameworka, dokumentacja często będzie nieaktualna lub niejasna. Może to prowadzić do wewnętrznej frustracji, gdy członek zespołu próbuje dodać funkcję, ale nie rozumie, jak działa bieżąca funkcja z powodu słabej dokumentacji. Może to prowadzić do bezproduktywnych godzin pracy.

Słaba dokumentacja zagraża również dobrej obsłudze klienta. Według Jeffa Lawsona, autora Ask Your Developer i założyciela Twilio, jeśli sprzedajesz interfejs API jako produkt, dokumentacja jest najlepszą reklamą dla interesariuszy technicznych . IBM przeprowadził badanie na temat znaczenia dokumentacji i 90% respondentów przyznało, że podejmowało decyzje zakupowe na podstawie jakości dokumentacji produktu.

Pisanie dobrej dokumentacji jest ważne dla doświadczeń dewelopera i klientów.

Skoro dokumentacja jest tak ważna, to dlaczego zespoły inżynierskie pomniejszają jej priorytety?

Pisanie dokumentacji może wyrwać programistów z „przepływu”. Dokumentacja często znajduje się poza główną bazą kodu , a jej wyszukiwanie i aktualizowanie jest kłopotliwe. Umieszczenie go w arkuszu kalkulacyjnym Excel lub zastrzeżonym CMS nie jest niczym niezwykłym.

Automatyzacja dokumentacji i usprawnienie przepływu dokumentacji rozwiązuje ten problem.

Automatyzacja dokumentacji z wysokiego poziomu

Co oznacza automatyzacja dokumentacji? Oznacza to przyjęcie wspólnych praktyk tworzenia oprogramowania. Kiedy automatyzujesz dokumentację, jesteś:

• pisanie dokumentacji w Markdown;
• używanie potoku ciągłej integracji i ciągłego wdrażania (CI/CD) do uruchamiania zadań, takich jak poprawianie błędów i wdrażanie aktualizacji (w tym samouczku wyróżnimy akcje GitHub);
• wdrażanie narzędzi takich jak Vale w celu egzekwowania przewodnika stylu i poprawiania typowych błędów gramatycznych.

Przewodniki po stylu

Zanim użyjesz narzędzi takich jak Vale i GitHub Actions do automatyzacji przewodnika po stylu, poświęćmy chwilę na zdefiniowanie, czym dokładnie jest przewodnik po stylu.

Znasz to uczucie, kiedy piszesz dokumentację i coś wydaje się trochę nie tak? Twoje wyjaśnienia nie pasują do reszty dokumentacji, ale nie możesz do końca opisać, dlaczego są błędne. Pismo wyjaśnia koncepcję, ale wydaje się, że nie pasuje.

Kiedy poczujesz to uczucie, twój głos i ton mogą być nieodpowiednie . Udoskonalenie głosu i tonu to sposób na sprawienie, by pisanie było spójne, nawet jeśli tworzysz dokumentację, która została zredagowana przez zespoły ds. kontroli jakości, inżynierii i produktu. Poniżej znajduje się przykładowy przewodnik po stylu aplikacji autobusów miejskich TAPP, zaczerpnięty z książki Pisanie strategiczne dla UX autorstwa Torreya Podmajersky'ego.

TAPP to aplikacja tranzytowa (dla autobusów i pociągów). Nagłówek tabeli przedstawia wartości TAPP jako firmy, która jest wydajna, godna zaufania i dostępna. Po lewej stronie tabeli wymieniono różne części objęte przewodnikiem stylu: pojęcia, słownictwo, szczegółowość, gramatyka i interpunkcja.

Razem tworzą one przewodnik po stylu . Nagłówek przedstawia wartości, a lewa strona tabeli pokazuje różne elementy, które można znaleźć w każdym materiale pisanym: słownictwo, gramatyka i interpunkcja. Piękno tego przewodnika po stylu polega na tym, że inżynierowie i copywriterzy będą wyraźnie wiedzieć, jakiej kapitalizacji użyć i jakiej interpunkcji użyć, aby promować tożsamość marki Tapp.

Przewodnik po stylu pisania technicznego

Nie wszystkie przewodniki po stylu są dostępne w tabelach. Firma Microsoft ma całą witrynę internetową, która służy jako kompleksowy przewodnik, obejmujący wszystko, od akronimów przez bezstronną komunikację po chatboty. Oczywiście Microsoft nie jest jedyną firmą, która ma przewodnik po stylu. Google też ma.

Kłopoty z przewodnikami po stylu

Przewodniki stylistyczne to świetny punkt wyjścia dla firm, które poważnie podchodzą do dokumentacji. Rozwiązują wiele nieporozumień, jakie mogą mieć programiści, co do tego, jak dokładnie pisać o głównej funkcji, którą wypuszczają.

Problem ze wskazówkami stylistycznymi polega na tym, że dodają one tarcia do procesu pisania. Wielu pisarzy, w tym ja, nie zadaje sobie trudu, aby przestać pisać i zaglądać do przewodnika po stylu za każdym razem, gdy mają pytanie. Czasami przewodnik po stylach jest niewygodny i zbyt trudny do odniesienia — na przykład przewodnik po stylach firmy Microsoft ma ponad tysiąc stron!

Linters i CI/CD do dokumentacji

Jeśli jesteś programistą, to prawdopodobnie znasz linters. Linters to idealny sposób na egzekwowanie standardów kodowania w Twoim zespole. To samo dotyczy dokumentacji. Tworząc linter, wyznaczasz punkt odniesienia dla jakości swojej dokumentacji. W tym samouczku użyjemy lintera Vale.

Używanie pewnego rodzaju automatyzacji dokumentacji wraz z linterem jest powszechne. Kiedy mówimy o automatyzacji w tym kontekście, mamy na myśli przepływ pracy ciągłej integracji i ciągłego wdrażania (CI/CD). CI automatyzuje tworzenie i testowanie dokumentacji . CD automatyzuje uwalnianie kodu.

Do wdrożenia przepływu pracy CI/CD można używać wielu różnych typów aplikacji. W tym samouczku użyjemy akcji GitHub do uruchomienia naszego lintera z dokumentacją. Akcje GitHub uruchamiają CI bezpośrednio w repozytorium GitHub, więc nie ma potrzeby korzystania z aplikacji innej firmy, takiej jak CircleCI lub Travis.

Wreszcie akcje GitHub są sterowane zdarzeniami , co oznacza, że ​​są wyzwalane, gdy coś się wydarzy, na przykład gdy ktoś napisze żądanie ściągnięcia lub problem. W naszym przykładzie akcja GitHub wystąpi, gdy ktoś wypchnie zmiany do swojej gałęzi głównej.

Akcje GitHub

Najpierw utwórz repozytorium GitHub. Następnie lokalnie utwórz folder i umieść w nim cd .

 mkdir automated-docs cd automated-docs

Gdy znajdziesz się w folderze, zainicjuj katalog dla Git.

 git init

Po zainicjowaniu repozytorium przejdź do utworzenia katalogu przepływu pracy w swoim folderze.

 mkdir .github/ && cd .github/ && mkdir workflows/ && cd workflows/

Przepływy pracy to miejsce, w którym będziemy przechowywać wszystkie nasze działania GitHub. Po utworzeniu folderu workflows utwórz nowy przepływ pracy. Będziemy nazywać ten przepływ pracy vale.yml .

 touch vale.yml

Vale.yml to plik YAML. W tym pliku przepływu pracy uwzględnimy akcje i zadania.

Teraz otwórz vale.yml w swoim ulubionym edytorze tekstu.

 nano vale.yml

Skopiuj i wklej poniższy kod do vale.yml i przejdźmy do kontekstu i składni.

 # This is a basic workflow to help you get started with Actions name: CI # Controls when the workflow will run on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ] pull_request: branches: [ main ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: # A workflow run is made up of one or more jobs that can run sequentially or in parallel jobs: # This workflow contains a single job called "build" build: # The type of runner that the job will run on runs-on: ubuntu-latest # Steps represent a sequence of tasks that will be executed as part of the job steps: # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - uses: actions/checkout@v2 # Runs a single command using the runners shell - name: Run a one-line script run: echo Hello, world! # Runs a set of commands using the runners shell - name: Run a multi-line script run: | echo Add other actions to build, echo test, and deploy your project. env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

• name
  To jest nazwa lub to, co nazywamy naszym przepływem pracy. To jest ciąg.
• on
  Kontroluje to przepływ pracy i wyzwalacze.
• jobs
  To tutaj ustalamy i kontrolujemy nasze działania. Wybieramy środowisko, w którym będą działać nasze działania — zwykle dobrze jest wybrać Ubuntu. I tu dodamy nasze działania.

GitHub ma przewodnik po wszystkich innych składniach i zmiennych przepływu pracy, jeśli jesteś ciekawy.

W tej sekcji mamy:

• dowiedziałeś się, czym są akcje GitHub,
• stworzyliśmy nasz pierwszy przepływ pracy GitHub,
• zidentyfikował najważniejsze części pliku YAML przepływu pracy GitHub.

Następnie dostosujemy nasz przepływ pracy GitHub do korzystania z Vale.

Skonfiguruj Vale w pliku działań GitHub

Po skopiowaniu podstawowego pliku przepływu pracy nadszedł czas, aby go dostosować, abyśmy mogli zacząć korzystać z akcji Vale. Pierwszą rzeczą do zrobienia jest zmiana nazwy pliku YAML na Docs-Linting .

 # This is a basic workflow to help you get started with Actions. name: Docs-Linting

Następnie chcemy uruchomić test Vale, gdy ktoś wypchnie swoje zmiany do głównej gałęzi na GitHub. Nie chcemy, aby test był uruchamiany, gdy ktoś utworzy żądanie ściągnięcia, więc usuniemy tę część pliku YAML.

 on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ]

Sekcja jobs jest główną częścią pliku przepływu pracy i odpowiada za uruchamianie akcji GitHub.

 jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@master

Te działania będą działać w najnowszej wersji Ubuntu. Akcja Checkout wyewidencjonowuje repozytorium, aby przepływ pracy GitHub mógł uzyskać do niego dostęp.

Teraz nadszedł czas, aby dodać akcję Vale do naszego przepływu pracy GitHub.

 - name: Vale uses: errata-ai/[email protected] with: debug: true styles: | https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

Nazwaliśmy naszą akcję Vale . Zmienna uses pokazuje, którą wersję Vale zamierzamy zaimplementować — najlepiej użyć najnowszej wersji. W zmiennej with ustawiamy debug na true .

Sekcja styles daje nam możliwość dodania przewodnika po stylu do Vale. W tym przykładzie write-good oficjalnego przewodnika po stylu Microsoftu. Pamiętaj, że możemy również skorzystać z innych poradników stylu.

Ostatnią częścią tej akcji GitHub jest env . Aby uruchomić tę akcję GitHub, musimy dołączyć tajny token.

Tak powinien wyglądać wynik:

 # This is a basic workflow to help you get started with Actions. name: Docs-Linting # Controls when the action will run. on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: jobs: prose: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@master - name: Vale uses: errata-ai/[email protected] with: debug: true styles: | https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

Po zakończeniu wprowadzania zmian zapisz plik, zatwierdź w Git i wypchnij zmiany do GitHub.

 git add .github/workflows/vale.yml git commit -m "Added github repo to project" git push -u origin main

Podsumowując, w tej sekcji mamy:

• wywołał akcję, która miała miejsce, gdy wepchniemy nowy kod do main gałęzi;
• dodano akcję Vale, ustawiając debug na true i identyfikując przewodniki stylów;
• dodano token GitHub;
• popełnione zmiany i przekazane do GitHub.

W następnej sekcji stworzymy plik konfiguracyjny Vale.

Konfiguracja pliku konfiguracyjnego wartości

Przejdź do katalogu głównego katalogu projektu, a następnie touch .vale.ini . Otwórz .vale.ini w edytorze tekstu. Skopiuj i wklej następujące dane do .vale.ini :

 StylesPath = .github/styles MinAlertLevel = warning [formats] Markdown = markdown [*.md] BasedOnStyles = write-good, Microsoft

• StylesPath = .github/styles
StylesPath podaje ścieżkę stylów Vale.
• MinAlertLevel = warning
  Minimalny poziom alertu pokazuje skalę ważności alertów. Dostępne opcje to suggestion , warning i error .
• [formats]
Markdown = markdown ustawia format jako Markdown.
• [*.md]
  Konfiguracja BasedOnStyles = write-good, Microsoft uruchomi dobry zapis i przewodnik po stylu Microsoft dla wszystkich plików Markdown kończących się na .md .

Taka konfiguracja to absolutne minimum. Jeśli chcesz dowiedzieć się więcej o konfigurowaniu Vale, przejdź do dokumentacji.

Po zakończeniu wprowadzania zmian zapisz plik, zatwierdź i wypchnij do GitHub.

 git add .vale.ini git commit -m "Added Vale config file" git push -u origin main

W tej części poznaliśmy elementy wewnętrzne pliku konfiguracyjnego Vale. Teraz czas na stworzenie przykładowej dokumentacji.

Tworzenie dokumentacji i uruchamianie akcji Vale GitHub

Teraz nadszedł czas, aby zobaczyć akcje Vale i GitHub w akcji! Stworzymy plik Markdown i wypełnimy go tekstem. A nasz tekst otrzymamy od DeLorean Ipsum.

Przejdź do katalogu głównego projektu, a następnie touch getting-started.md . Po utworzeniu pliku getting-started przejdź do DeLorean Ipsum i utwórz fikcyjny tekst dla swojej dokumentacji. Następnie wróć do edytora tekstu i wklej tekst w getting-started-md .

 # Getting Started Guide I can't play. It's my dad. They're late. My experiment worked. They're all exactly twenty-five minutes slow. Marty, this may seem a little foreward, but I was wondering if you would ask me to the Enchantment Under The Sea Dance on Saturday. Well, they're your parents, you must know them. What are their common interests, what do they like to do together? Okay. Are you okay? Whoa, wait, Doc. What, well you mean like a date? I don't wanna see you in here again. No, Biff, you leave her alone. Jesus, George, it's a wonder I was ever born. Hey, hey, keep rolling, keep rolling there. No, no, no, no, this sucker's electrical. But I need a nuclear reaction to generate the one point twenty-one gigawatts of electricity that I need. I swiped it from the old lady's liquor cabinet. You know Marty, you look so familiar, do I know your mother?

Zapisz plik, zatwierdź go i wypchnij do GitHub.

 git add getting-started.md git commit -m "first draft" git push -u origin main

Po wypchnięciu zmian przejdź do GitHub, gdzie znajduje się Twoje repozytorium. Przejdź do zakładki Actions .

Zobaczysz wszystkie swoje przepływy pracy po lewej stronie. Mamy tylko jedną, nazwaną Docs-Linting , taką samą nazwę umieściliśmy w pliku vale.yml .

Kiedy wypchniemy dokumentację do GitHub, uruchomimy akcję.

Jeśli akcja przebiegła bez problemów, dostaniemy zielony znacznik wyboru.

Kliknij „Dodane dokumenty”, aby uzyskać pełny raport.

Zobaczysz, że otrzymaliśmy 11 ostrzeżeń. Zajmijmy się ostrzeżeniem „łasica”. Wróć do edytora tekstu, otwórz getting-started.md i usuń słowo „dokładnie”.

 # Getting Started Guide I can't play. It's my dad. They're late. My experiment worked. They're all twenty-five minutes slow. Marty, this may seem a little foreward, but I was wondering if you would ask me to the Enchantment Under The Sea Dance on Saturday. Well, they're your parents, you must know them. What are their common interests, what do they like to do together? Okay. Are you okay? Whoa, wait, Doc. What, well you mean like a date? I don't wanna see you in here again. No, Biff, you leave her alone. Jesus, George, it's a wonder I was ever born. Hey, hey, keep rolling, keep rolling there. No, no, no, no, this sucker's electrical. But I need a nuclear reaction to generate the one point twenty-one gigawatts of electricity that I need. I swiped it from the old lady's liquor cabinet. You know Marty, you look so familiar, do I know your mother?

Zapisz zmiany, zatwierdź je w Git i wypchnij nową wersję pliku do GitHub. Powinno to wywołać akcję GitHub .

Jeśli klikniemy „Usunięto słowo łasica”, zobaczymy, że mamy teraz tylko 10 ostrzeżeń, a ostrzeżenie „słowo-łasicy” zniknęło. Hurra!

Jesteśmy skończeni i przebyliśmy dużo terenu. W tej sekcji mamy:

• dodano dokumentację do naszego repozytorium Vale GitHub Actions,
• wywołał akcję Vale GitHub,
• poprawiono błąd generowany przez Vale i przesłałem zmianę z powrotem do GitHub.

Wniosek

W świecie, który jest coraz bardziej zdalny, ważne jest nadanie priorytetu dobrej dokumentacji i dobremu przepływowi dokumentacji. Najpierw musisz zdefiniować, co jest „dobre”, tworząc przewodnik stylu. Kiedy już poznasz zasady swojej dokumentacji, nadszedł czas na automatyzację.

Dokumentację należy traktować jak bazę kodu: żywą pracę, która jest stale iterowana i staje się nieco lepsza niż przy ostatniej aktualizacji.