Przybywam tu z elitarnego portalu wypok. Miałem ostatnio w pracy zadanie rozpoznania tematu formatu .adoc w pisaniu dokumentacji, i pomyślałem, że nada się też do SUPLI. Aby nie przedłużać...
Zauważyłem, że o ile instrukcje do modułów sprzedawanych przez firmę ZAMEL są bardzo dobrze zrobione, to te do gniazdka WiFi, modułu bramowego itd. krótko mówiąc... odstają poziomem. I tu mógłbym pomóc nieco w rozwoju dokumentacji.
Jest taki format/język programowania? jak asciidoc, służy on do pisania dokumentacji. Pliki posiadają rozszerzenie .adoc. Asciidoc przypomina Markdown i jest również interpretowany na githubie.
Zasadniczą zaletą pisania w asciidoc jest to że pisząc skupiamy się na treści dokumentu, nie na formatowaniu. Ponadto asciidoc pozwala na dodawanie instrukcji warunkowych, dzielenie dokumentu na podrozdziały w osobnych plikach, importowanie plików .csv do tabel itd.
Aby się tu zbytnio nie rozpisywać zapraszam pod ten link po więcej:
https://asciidoctor.org/docs/what-is-asciidoc/
No i fajnie, no i spoko, ale po co to komu?
Z plików w asciidoc możemy generować strony HTML lub pliki .PDF
Tak jak pisałem wyżej - plik zawiera treść, formatowanie jest zależne od pliku .css dla HTML albo pliku motywu .yml dla generowania plików .pdf, ponadto mamy instrukcje warunkowe i inne bajery.
Dzięki temu można stworzyć jednolity styl dokumentacji - plik motywu, który będzie wspólny dla generowanych dokumentów.
W przypadku zmiany np. logo, wielkości nagłówków, przypisów w stopce itd. trzeba edytować tylko plik motywu. Cała dokumentacja zostanie przebudowana według niego automatycznie.
Dodatkowo dzięki instrukcjom warunkowym można robić dokumenty wielojęzyczne mniej więcej tak:
Code: Select all
ifeval::["{lang}" == "pl"]
Witaj SUPLA
sekcja tekstu po polsku.
endif::[]
ifeval::["{lang}" == "en"]
Hello SUPLA
text section in english.
endif::[]
W załączniku dodaję plik pdf - fragmenty instrukcji do gniazdka wifi wygenerowany z użyciem napisanego przeze mnie motywu dla supli.
Jak wygląda ten tekst w asciidoc można zobaczyć tutaj:
https://pastebin.com/LytsB89E
Ta instrukcja jest niekompletna, ale nie o to tu chodzi. Jak podoba Wam się formatowanie(nagłówki, stopki, strona tytułowa)? Rzeczy takie jak spis treści, daty, nazwy rozdziałów w nagłówkach i stopkach, numeracje, itd. są generowane automatycznie.
Jak bym to widział w przypadku SUPLI:
repo na github:
supla-adoc-common zawierające motyw, obrazki użyte w motywie, pliki lokalizacji(obsługa języków), czcionki motywu. Trzymałbym tu też na przykład screeny konfiguracji w przeglądarce i na smartfonie. Interfejs SUPLi ewoluuje, i obrazy te w instrukcjach nie są aktualne. Tu wystarczyłoby je aktualizować w jednym miejscu, i z automatu leciałoby to na całą dokumentację odwołującą się do tych obrazów.
W repozytoriach z projektami pliki .adoc z instrukcjami i dołączonym supla-adoc-common zewnętrznie jako submodule, a także skryptem .sh/.bat do generowania plików .pdf
