Podstawy tworzenia i redagowania tekstów specjalistycznych Dokumentacja techniczna

Transkrypt

1 Podstawy tworzenia i redagowania tekstów specjalistycznych Dokumentacja techniczna Katarzyna Klessa

2 Do kogo kierujemy naszą dokumentację/pomoc? Jeśli pojęcie Grupa użytkowników: 'baza danych' to dla nas po prostu jakikolwiek zbiór danych, to na powyższe pytanie możemy - gdzie użytkownik będzie korzystał z dokumentacji (np. Urządzenia mobilne, stacjonarnie?) Ograniczenia - w jaki sposób? - brak powiązań - okazjonalnie, między systematycznie? poszczególnymi Czy plikami, przeczyta trudności w całości w sortowaniu czy raczej ze będzie względu sięgać na tylko różne w razie kryteria, potrzeby? trudności we współpracy, gdy dane są edytowane 2

3 Organizacja treści Jeśli pojęcie - czy można 'baza wyróżnić danych' zagadnienia to dla nas częściej po prostu i rzadziej jakikolwiek zbiór danych, interesujące to na użytkownika? powyższe Jakie? pytanie możemy - jeśli tak Często zadawane pytania (FAQ) lub inny sposób wyróżnienia tych zagadnień, np. zamieszczenie Ograniczenia ich na początku - brak powiązań dokumentacji między poszczególnymi plikami, - trudności czy spodziewamy w sortowaniu się, że użytkownik ze względu zna podstawy na różne kryteria, opisywanego trudności we przez współpracy, nas narzędzia gdy czy dane zagadnienia, są edytowane np. przez różne opisu metodologii? osoby (kto - edytuje, jeśli nie który porównanie plik, kiedy, z co zostało istniejącymi, bardziej popularnymi rozwiązaniami 3

4 Organizacja treści Jeśli pojęcie - uporządkowanie 'baza danych' tematów, to dla zagadnień nas po w prostu taki sposób, jakikolwiek aby zbiór danych, użytkownik to na mógł powyższe jak najsprawniej pytanie skorzystać możemy z dokumentacji: jakie są pierwsze kroki użytkownika w celu skorzystania z opisywanego narzędzia/metody? Co może Ograniczenia stanowić - problem? brak powiązań Jeśli mógł między wcześniej poszczególnymi korzystać z plikami, innych trudności narzędzi w sortowaniu zwrócić szczególną ze względu uwagę na na różne różnice. kryteria, trudności we współpracy, gdy dane są edytowane 4

5 Organizacja treści Jeśli pojęcie - poszczególne 'baza danych' elementy to dokumentacji dla nas po nie prostu powinny jakikolwiek być zbiór danych, zbyt obszerne to na powyższe jeśli opisywany pytanie problem możemy jest złożony, lepiej podzielić opis na kilka punktów Ograniczenia - brak powiązań między poszczególnymi plikami, trudności w sortowaniu ze względu na różne kryteria, trudności we współpracy, gdy dane są edytowane 5

6 Organizacja treści Jeśli pojęcie - jeśli dokumentacja 'baza danych' składa to dla się z nas kilku po części, prostu to na jakikolwiek zbiór danych, pierwszej to stronie na powyższe dobrze jest pytanie zamieścić możemy informację o pozostałych częściach / tomach - jeśli tworzymy kolejną wersję dokumentacji, która Ograniczenia wcześniej - brak była już powiązań udostępniana między użytkownikom, poszczególnymi to plikami, koniecznie trudności należy w sortowaniu dokładnie podać ze względu numer wersji, na różne również kryteria, na trudności pierwszej stronie we współpracy, gdy dane są edytowane 6

7 Dygresja nazewnictwo... po co to komu? - uzgodnienie stylu nazewnictwa plików, stylu zapisu Jeśli pojęcie zazwyczaj 'baza dokładny danych' opis stylu to dla nazewnictwa nas po prostu bardzo ułatwia jakikolwiek I zbiór danych, przyspiesza to na pracę powyższe własną i zespołu pytanie możemy odpowiedzieć - dokumentowanie - 'tak' nazewnictwa, stylu zapisu - jeśli istnieją standardy lub uzgodnione w zespole reguły Ograniczenia zachowujmy - brak je, nawet powiązań jeśli w danej między chwili poszczególnymi wydają nam się plikami, przesadzone trudności w (np. sortowaniu stosowanie wielkich ze względu i małych liter na w różne kodzie kryteria, programistycznym, trudności we współpracy, tam gdzie jest to gdy tylko dane umowne są i nie edytowane wpływa na funkcjonalność) 7

8 Dygresja nazewnictwo... - Teraz to zajmie mniej czasu, niż później:) - w programowaniu zapoznajmy się z obowiązującymi Jeśli pojęcie konwencjami 'baza I danych' korzystajmy to z dla nich nas świadomie po prostu jakikolwiek zbiór danych, - datowanie na powyższe pytanie możemy odpowiedzieć - nazwa - informuje 'tak' o zawartości - nazwa powinna zawierać przede wszystkim elementy Ograniczenia informatywne - brak powiązań między poszczególnymi plikami, - trudności jeśli plik przeznaczony w sortowaniu dla Internetu ze względu unikać znaków różne polskich, kryteria, podkreślniki, trudności myślniki we współpracy, zamiast spacji gdy dane są edytowane - jeśli plik jest archiwizowany nazwa taka, byśmy w przyszłości przez różne też łatwo osoby przypomnieli (kto edytuje, sobie, jak który ją rozumieć plik, kiedy, co zostało - jeśli współpracujemy z innymi ludźmi nazwa jest taka, aby oni Systemy też wspomagające łatwo rozumieli pracę jeśli trzeba na zbiorach plików, np. Git - dokładnie opisujemy strukturę nazwy plików, zob. przykład 8

9 Organizacja treści Jeśli pojęcie - jeśli dokumentacja 'baza danych' składa to dla się z nas kilku po części, prostu to na jakikolwiek zbiór danych, pierwszej to stronie na powyższe dobrze jest pytanie zamieścić możemy informację o pozostałych częściach / tomach - jeśli tworzymy kolejną wersję dokumentacji, która Ograniczenia wcześniej - brak była już powiązań udostępniana między użytkownikom, poszczególnymi to plikami, koniecznie trudności należy w sortowaniu dokładnie podać ze względu numer wersji, na różne również kryteria, na trudności pierwszej stronie we współpracy, gdy dane są edytowane 9

10 HelpNDoc: Jeśli pojęcie 'baza danych' to dla nas po prostu jakikolwiek zbiór danych, to na powyższe pytanie możemy Ograniczenia - brak powiązań między poszczególnymi plikami, trudności w sortowaniu ze względu na różne kryteria, trudności we współpracy, gdy dane są edytowane 10

11 Dziękuję za uwagę!