Dokumentowanie języka programowania: Instrukcja obsługi

Patrzymy na dokumentację dotyczącą modernizacji w całej naszej linii produktów. Część z nich obejmuje podręczniki do języka programowania używanego jako część systemu.

Kiedy pisząc instrukcję obsługi dla języka programowania, jaki jest najlepszy sposób, aby go ustrukturyzować, aby zapewnić maksymalną użyteczność osobom początkującym w języku?

Jakie są kluczowe aspekty każdego udokumentowanego słowa kluczowego?

• Składnia
• Opis
• Argumenty - jeśli dotyczy
• Zwracane wartości - jeśli dotyczy
• Przykład użycia
• Czy jeszcze kogoś brakuje?

Czy pojęcia (takie jak strategie blokowania, szczegóły związane z wydajnością) powinny być również udokumentowane w tym podręczniku, czy jest to osobny dokument?

_{To jest do użytku zewnętrznego. Mamy już pełne zestawy dokumentów (patrz: http://www.rocketsoftware.com/u2/resources/technical-resources ). Rozpracowując, co powinniśmy zrobić inaczej - mam już swoje pomysły, ale jak zwykle staram się nie polegać wyłącznie na mojej opinii.}

_{Odbiorcy: Deweloperzy techniczni używający naszych baz danych i narzędzi do tworzenia oprogramowania w wielu branżach.}

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:

1. 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.}

2. Podstawy.
   Dla facetów, którzy chcą szybko nauczyć się rzeczy niezbędnych do rozpoczęcia produkcji działającego oprogramowania.
3. 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 .
4. 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.}
5. 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.

^{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:

1. 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.
2. 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ę .}

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?}

Pierwszą rzeczą, którą musisz zrobić, to ocenić odbiorców. Czy Twoi odbiorcy hakerzy jądra Linuksa czy projektanci sprzętu komputerowego używają narzędzi do wykonywania pracy, ale nie są zainteresowani oprogramowaniem jako takim i nie mają doświadczenia w CS. Inżynierowie elektryczni najprawdopodobniej nie będą do końca jasne na temat różnic między argumentami const i non-const, wskaźnikami do obiektów a referencjami itp. Jeśli twoje prymitywy mają przeciążone nazwy, lepiej wyjaśnij tę koncepcję na odpowiednim poziomie dla odbiorców, co może być niczym, jeśli są programistami C ++.

Drugą rzeczą, którą musisz ocenić, jest szczegółowość prymitywów języka. Im drobniejsza ziarnistość, tym bardziej trzeba podać przykłady użycia w pobliżu specyfikacji składni każdego elementu pierwotnego. To znaczy, jeśli masz operację podstawową niskiego poziomu, która tworzy pewien kontekst, i musisz operować nią z trzema innymi operacjami podstawowymi niskiego poziomu, zanim będziesz w stanie zrobić coś użytecznego, lepiej mieć pełny przykład przydatnej funkcji close- przez w instrukcji. Zapoznaj się z dokumentacją openssl online, aby uzyskać doskonały kontrprzykład dokumentacji prawie bezużytecznej.

Pamiętaj, aby dołączyć wyjaśnienie wszelkich skutków ubocznych swoich funkcji.

W każdym razie, jeśli nie chcesz, aby programiści twojego klienta przeklinali cię każdej nocy przed snem, dołącz mnóstwo przetestowanego przykładowego kodu, który wykonuje pewne funkcjonalne funkcje wysokiego poziomu. Upewnij się, że przykłady nie są tylko fragmentami kodu, ale są kompletne, kompilowalne lub uruchamialne po wyjęciu z pudełka.

Tradycyjnie pisarze technologii rozróżniają podręczniki referencyjne i podręczniki użytkownika . Podręcznik referencyjny zwykle zawiera specyfikacje składni, zrozumiałą definicję funkcji lub operacji podstawowych, omówienie gotcha, wydajności i skutków ubocznych oraz krótki przykład użycia. Podręcznik użytkownika zawiera bardziej rozbudowane przykłady użycia i omówienie szerszych problemów inżynieryjnych. „C Programming Language” Kernigan i Ritchie jest doskonałym przykładem dla tej konwencji, ale to podejście działa tylko wtedy, gdy dokumentowany język jest stosunkowo prosty.

Autor był kierownikiem działu usług inżynieryjnych w centrum rozwoju Ready Systems Inc w latach 1987-1991, odpowiadając za zarządzanie zespołem pięciu pisarzy technicznych.