Być może z rozpędu czy też przyzwyczajenia przejście od razu do części praktycznej tego przewodnika wydało Ci się dobrym pomysłem. Jeśli tak się stało, to zachęcam Cię do przeczytania części teoretycznej, żeby dowiedzieć się jaki miałem cel pisząc ten przewodnik i jakie powinny być Twoje oczekiwania w stosunku do tego co tu znajdziesz.
Co będziemy robić?
Jak to co? Kodować w Pythonie! 🙂
W świecie dokumentacji do oprogramowania, istnieje wiele miejsc, gdzie tradycyjne "kopiuj-wklej" można potencjalnie zastąpić jakimś automatycznym rozwiązaniem, które odwali za nas brudną robotę.
Wyobraź sobie taki scenariusz. Dostajesz przydział do projektu, w którym
będziesz bardzo blisko współpracować z programistami. Ustaliliście na samym
początku, że za każdym razem kiedy programista zrobi zmianę w kodzie, która musi
zostać udokumentowana, doda do folderu docs
plik tekstowy z opisem zmian. Plik
będzie miał taką nazwę jak numer historyjki w systemie do śledzenia zadań. Na
przykład, jeśli historyjka ma numer PROJ-102 i została stworzona po to, żeby
programista naprawił błąd powodujący, że aplikacja zawieszała się na kilka
sekund, a następnie okno aplikacji przesuwało się poza ekran, to programista w
repozytorium z kodem doda plik docs\PROJ-102.txt
, w którym będzie taka
informacja.
PROJ-102.txt
Naprawiliśmy błąd, który powodował, że aplikacja zawieszała się na kilka sekund, a następnie okno aplikacji przesuwało się poza ekran przez co stawało się niewidoczne.
Co kilka tygodni zespół publikuje nową wersję aplikacji wraz z aktualną dokumentacją, której częścią są release notes (noty wydania). Treść, która trafia do release notes pochodzi z plików tekstowych, które dodają programiści kiedy zmieniają kod. Twoim zadaniem, jako Tech Writera, jest sprawdzanie informacji w tych plikach, poprawianie ich, a na końcu wygenerowanie pliku HTML z gotowymi notami. Jest to prosty plik z tabelką przedstawiającą zmiany w aplikacji. Chodzi o coś takiego.
Numer zgłoszenia | Opis |
---|---|
PROJ-102 | Naprawiliśmy błąd, który powodował, że aplikacja zawieszała się na kilka sekund, a następnie okno aplikacji przesuwało się poza ekran przez co stawało się niewidoczne. |
PROJ-101 | Dodaliśmy nową funkcję, która pozwala na szybkie pobieranie zasobów sieciowych. |
Nie chcesz generować pliku HTML poprzez ręczne przeklejanie informacji z plików tekstowych i potem wprowadzanie pozostałych poprawek, dlatego szukasz bardziej sprytnego rozwiązania. Chcesz swój czas i energię przeznaczyć głównie na ulepszanie informacji, które dostarczają Ci programiści, a proces publikowania końcowego pliku chcesz przekazać maszynie.
I to właśnie będzie nasz cel, który będziemy krok po kroku realizować w kolejnych sekcjach. Zbudujemy razem przykładowy generator treści, który pobiera informacje z plików tekstowych, a następnie generuje docelowy plik HTML na podstawie szablonu.