Organizuj dokumentację zgodnie z potrzebami odbiorców docelowych.
W twoim przypadku głównymi odbiorcami są najwyraźniej twórcy oprogramowania. Części do rozważenia w tym miejscu dotyczą różnych „pod-odbiorców” tego:
- Witaj świecie.
Ci, którzy chcą szybko poznać jego smak, wystarczy zbudować i uruchomić przykładową aplikację, aby zobaczyć, jak to wygląda.
Pomyśl o publiczności, jak ta, do której odnosi się MySQL „zasada 15 minut” :
... użytkownik, aby móc uruchomić MySQL w 15 minut po jego pobraniu.
- Podstawy.
Dla facetów, którzy chcą szybko nauczyć się rzeczy niezbędnych do rozpoczęcia produkcji działającego oprogramowania.
- Zaawansowane tematy.
Dla programistów, którzy już dobrze znają i ćwiczyli podstawy, chcą wiedzieć, co jest poza nimi. Główne tematy, które nie zostały omówione w Podstawach .
- Przewodnik po stylu / zalecane praktyki.
Subiektywne porady i wskazówki dla osób zainteresowanych sposobem, w jaki zalecasz robić rzeczy.
Pytanie nie wskazuje, czy może to mieć znaczną grupę odbiorców w twoim przypadku, więc opcje do rozważenia to włączenie go jako części / załącznika tematów zaawansowanych, a nawet całkowite upuszczenie.
- Dziwactwa.
Niewyraźne tematy, poza głównym nurtem, które mogą zainteresować dość ograniczoną część odbiorców. Na przykład, jeśli masz starszą linię lub rzeczy takie jak uaktualnienie / migracja / interoperacyjność ze starszą wersją - umieść ją tutaj. Jeśli występują jakieś skutki uboczne dla niektórych funkcji w określonym „egzotycznym” środowisku, dzieje się to w tej części.
Druga grupa odbiorców jest opiekunami podręcznika. Ci faceci mogą zmienić lub zepsuć sposób działania głównych odbiorców, więc lepiej zadbaj o ich potrzeby i problemy.
Co jeśli coś w podręczniku jest wątpliwe / niejednoznaczne? Co jeśli okaże się, że dokładne objaśnienie poszczególnych pojęć spowodowałoby, że ten podręcznik byłby zbyt trudny do przeczytania? Co się stanie, jeśli okaże się, że konkretna wersja instrukcji zawiera błędy?
Dwie rzeczy do rozważenia dla opiekunów to:
- Specyfikacja techniczna / formalna.
Ilekroć w podręczniku pojawia się wątpliwy / dwuznaczny / trudny do wyjaśnienia temat, czytelnik może zostać odsyłany do konkretnego akapitu specyfikacji w celu uzyskania ścisłego i jasnego, „oficjalnego” oświadczenia w tej sprawie. Ścisły i kompletny (i najprawdopodobniej nudny) opis składni językowej lepiej tam pójść.
Najważniejsze kwestie dotyczące specyfikacji to dokładność techniczna i kompletność, nawet jeśli dzieje się to kosztem czytelności.
- Dodatek online.
Wystarczy zarezerwować adres URL i umieścić go na początku każdego wydawanego dokumentu, aby faceci zastanawiając się, co, do cholery, właśnie przeczytali, mogli tam przejść (zamiast męczyć ręcznych opiekunów) i znaleźć wyjaśnienie błędu.
Errata> Podstawy> Wydanie 2.2> Literówka na stronie 28, drugie zdanie zaczyna się od szczęścia , zamiast tego przeczytaj blokadę .
Pojęcia takie jak strategie blokowania, szczegóły związane z wydajnością powinny zostać uwzględnione (możliwe częściowo) tam, gdzie oczekujesz, że będą potrzebować docelowej grupy odbiorców.
Np. Opiekunowie ręczni najwyraźniej byliby zainteresowani pełnym, dokładnym opisem współbieżności i blokowaniem specyfikacji formalnej - umieść ją tam. Czytelnicy podstaw lub tematów zaawansowanych mogą być zainteresowani przeglądem / wprowadzeniem / przewodnikiem wyodrębnionym ze specyfikacji i dostosowanym do ich potrzeb itp.
Pomocne może być zorganizowanie analizy porównawczej dokumentacji referencyjnej dla innych języków, takich jak Twój. Skieruj to badanie na wykorzystanie doświadczenia zdobytego przez tych, którzy to robili wcześniej, i naucz się, jak unikać popełnianych błędów.
Ostatnim, ale nie mniej ważnym, jest rozważenie opracowania dokumentacji w sposób podobny do tworzenia oprogramowania. Chodzi mi o takie rzeczy, jak kontrola wersji, regularne wydania, śledzenie problemów, zapewnianie jakości itp. Możesz jednak pójść na kompromis, jeśli okaże się, że twoi pisarze techniczni nie są zbyt zadowoleni z takich rzeczy. Nie chcemy, aby gówniane treści były „w zamian” za doskonały proces rozwoju, prawda?