Czy zwracasz uwagę na czytelność dokumentacji, którą przygotowujesz?
Spójrz na poniższe, autentyczne wymaganie:
„SYSTEM musi umożliwiać: komunikację z otoczeniem poprzez: e-mail, SMS, FTP, http, HTTPS, replikację danych, wymianę danych przez mechanizm WebService w każdym obszarze funkcjonalnym, bezpośredni dostęp do danych przechowywanych w bazie danych bez konieczności nabywania dodatkowej licencji lub innych kosztów związanych z tym dostępem, w oparciu o aktualną dokumentację tabel oraz powiązań między nimi dostarczaną przez Wykonawcę bez dodatkowych warunków.„
Jak poprawić czytelność w takim przypadku?
Wystarczy, że zastosujesz standardy znane od kilkudziesięciu lat.
Dokumentacja powinna być pod kontrolą
Do dokumentacji warto podejść jak do pisania kodu. Programiści mają określone standardy kodowania. Do tego korzystają z narzędzi, które weryfikują składnię i wyłapują błędy. Bez tego każdy pisałby kod według swoich preferencji. A potem nikt inny by go nie rozumiał.
Żeby poprawić czytelność dokumentacji stworzono więc tzw. Controlled natural languages (CNLs). Są to nakładki na język naturalny, które wymuszają użycie tylko określonych form, czasów itp. Celem jest większa przejrzystość, jednoznaczność i mniejsza złożoność.
CNL jest też kluczowym zagadnieniem w maszynowej interpretacji języka. Sztuczna inteligencja dużo lepiej radzi sobie z prostymi wyrażeniami, niż zdaniami wielokrotnie złożonymi. Ale to temat na inny artykuł.
Metoda znana od ponad 40 lat – STE
Przemysł lotniczy zauważył potrzebę poprawy czytelności dokumentacji już w latach 80-tych XX. Dzięki standaryzacji i uproszczeniu języka możliwa była wymiana wiedzy pomiędzy ośrodkami amerykańskimi, angielskimi i całą resztą świata.
Rozwiązanie to nazywa się obecnie ASD Simplified Technical English, Specification ASD-STE100. Zawiera szereg zasad, których należy przestrzegać przygotowują specyfikację. Firmy takie jak Boeing posiadają narzędzia, które weryfikują zgodność specyfikacji ze standardem STE.
STE w praktyce
Przykładowe zasady uproszczonego języka, to:
Usuwaj nadmiarowe wyrażenia, przykładowo: „w specyficznej sytuacji użytkownik może zdecydować się wyłączyć tryb automatyczny i przejść na sterowanie ręczne”
Ograniczaj długość zdań do maksymalnie 20 wyrazów dla procedur i 25 dla opisów.
Korzystaj ze słownika wyrażeń. Standard STE udostępnia słownik – listę typowych wyrażeń i ich interpretację. Przykładowo „should” należy zastępować słowem „must”. Niedopuszczalne jest wyrażenie „Personel should wear protective clothing”, ponieważ nie precyzuje na ile noszenie odzieży ochronnej jest obowiązkowe.
Możesz też stworzyć własny słownik w ramach konkretnej dokumentacji.
Unikaj slangu i żargonu. Każdy kraj ma swoje dodatki językowe. Tak samo z jednostkami. Wyrażenie „Use a foot-long breaker bar during this procedure” jest niejednoznaczne. Jednostkę „foot” należy zamienić np. na milimetry lub cale.
W j. angielskim stosuj as a/an przed rzeczownikami. Dzięki temu czytelnik wie od razu kiedy jest mowa o przedmiotach, a kiedy o czynnościach. Np. „This data module tells you how to operate the unit.” Bez wyrażeń podkreślonych na zielono też by mogło być, ale byłoby mniej czytelnie.
Używaj prostych czasów i wyłącznie formy czynnej. Czyli upraszczaj formy, zamiast je komplikować. Zamiast „Plastic is not used in this product” napisz „We don’t use plastic in this product”. Unikaj form zaprzeszłych, trybów przypuszczających i podobnych komplikacji. Tylko podstawowe struktury zdania. Jak w pierwszej klasie podstawówki.
Rozbijaj zdania złożone na poszczególne kroki. Jedno zdanie – jedna akcja. Jeżeli istotna jest kolejność to zastosuj numerację kroków. Na przykład zamiast „User can create an account, then log in and select the location” wypisz kolejne kroki:
1. Create an account.
2. Log into the system.
3. Choose the location.
Narzędzia do weryfikacji anglojęzycznej dokumentacji
W pracy nad czytelnością dokumentacji pomogą Ci różne narzędzia. Jednym z najpopularniejszych jest Grammarly.
Aplikacja ta nie jest w 100% zgodna ze standardem STE, ale stosuje bardzo podobne reguły.
Na przykład sugeruje poprawić stronę bierną:
Podobnie ze zdaniami złożonymi i ogólnie czytelnością:
Do profesjonalnego sprawdzania zgodnie z STE możesz użyć np. produktu firmy congree: https://www.congree.com/en/ste-simplified-technical-english
Polskojęzyczne narzędzia do poprawy czytelności dokumentacji
Jeżeli piszesz dokumentację po polsku to sięgnij na przykład po Jasnopis.
Aplikacja oceni Twój tekst pod kątem trudności zrozumienia. Zasugeruje też które wyrażenia zmienić, aby poprawić czytelność dokumentacji.
Przykładowo, dla fragmentu tego artykułu:
Ocena jest 4/7 a problematyczne słowa to:
- wyrażanie,
- niejednoznaczne.
Jeżeli interesuje Cię temat wysokiej jakości specyfikacji to koniecznie przeczytaj ten artykuł na temat procesu poprawy jakości dokumentacji:
