Dokumentieren einer Programmiersprache: Referenzhandbuch

Wir prüfen die Überarbeitung der Dokumentation für unsere gesamte Produktlinie. Ein Teil davon enthält Referenzhandbücher für eine Programmiersprache, die als Teil des Systems verwendet wird.

Wie kann ein Referenzhandbuch für eine Programmiersprache am besten strukturiert werden, um eine maximale Benutzerfreundlichkeit für diejenigen zu gewährleisten, die neu in der Sprache sind?

Was sind die wichtigsten Aspekte für jedes dokumentierte Keyword?

• Syntax
• Beschreibung
• Argumente - falls zutreffend
• Rückgabewerte - falls zutreffend
• Anwendungsbeispiel?
• Vermisse ich noch andere?

Sollten Konzepte (wie Sperrstrategien, leistungsbezogene Details) auch in diesem Referenzhandbuch dokumentiert werden, oder handelt es sich um ein separates Dokument?

_{Dies ist für den externen Verbrauch. Wir haben bereits vollständige Dokumentensätze (siehe: http://www.rocketsoftware.com/u2/resources/technical-resources ). Überlegen, was wir anders machen sollen - ich habe bereits meine Ideen, aber wie immer versuche ich, mich nicht nur auf meine Meinung zu verlassen.}

_{Zielgruppe: Technische Entwickler, die unsere Datenbank (en) und Tools verwenden, um Software in vielen Branchen zu erstellen.}

Organisieren Sie die Dokumentation entsprechend den Anforderungen der Zielgruppe.

In Ihrem Fall sind anscheinend hauptsächlich Softwareentwickler das primäre Publikum. Die Teile, die hier zu berücksichtigen sind, richten sich an verschiedene "Untergruppen" dieser:

1. Hallo Welt.
   Diejenigen, die bereit sind, schnell einen Eindruck davon zu bekommen, erstellen und führen einfach eine Beispielanwendung aus, um zu sehen, wie sie aussieht.
   Stellen Sie sich das Publikum wie eine von MySQL angesprochene "15-Minuten-Regel" vor :
   

   _{... ein Benutzer, der MySQL 15 Minuten nach dem Herunterladen zum Laufen bringen kann.}

2. Grundlagen.
   Für die Jungs, die bereit sind, schnell die notwendigen Dinge zu lernen, um mit der Produktion funktionierender Software zu beginnen.
3. Fortgeschrittene Themen.
   Für Entwickler, die bereits mit den Grundlagen vertraut und geübt sind und interessiert sind, was dahinter steckt. Mainstream-Themen, die in den Grundlagen nicht behandelt wurden .
4. Style Guide / Empfohlene Vorgehensweisen.
   Subjektive Beratung und Anleitung für diejenigen, die daran interessiert sind, wie Sie Dinge empfehlen.
   _{Die Frage gibt nicht an, ob dies in Ihrem Fall ein beträchtliches Publikum haben könnte. Daher sollten Sie in Betracht ziehen, es als Teil / Anhang der erweiterten Themen aufzunehmen oder es sogar vollständig zu löschen.}
5. Macken.
   Obskure Themen außerhalb des Mainstreams, die für einen relativ begrenzten Teil Ihres Publikums von Interesse sein könnten. Wenn Sie beispielsweise eine Legacy-Leitung haben oder Dinge wie Upgrade / Migration / Interoperabilität mit Legacy - setzen Sie diese hier. Wenn es in einer bestimmten "exotischen" Umgebung einige Nebenwirkungen für eine Funktion gibt, wird dies in diesem Teil beschrieben.

^{Was ist, wenn etwas im Handbuch fragwürdig / mehrdeutig ist? Was wäre, wenn sich herausstellen würde, dass eine gründliche Erklärung bestimmter Konzepte das Lesen dieses Handbuchs zu schwierig machen würde? Was ist, wenn sich herausstellt, dass eine bestimmte Version des Handbuchs Fehler enthält?}

Zwei Dinge, die für Betreuer zu beachten sind, sind:

1. Technische / formale Spezifikation.
   Immer wenn das Handbuch ein fragwürdiges / mehrdeutiges / schwer zu erklärendes Thema enthält, kann der Leser auf einen bestimmten Absatz in der Spezifikation verwiesen werden, um eine strenge und klare, "offizielle" Erklärung dazu zu erhalten. Eine strenge und vollständige (und höchstwahrscheinlich langweilige) Beschreibung der Sprachsyntax sollte besser dorthin gehen.
   Wichtige Überlegungen für die Spezifikation sind technische Genauigkeit und Vollständigkeit, auch wenn diese auf Kosten der Lesbarkeit gehen.
2. Online-Beilage.
   Reservieren Sie einfach eine URL und setzen Sie sie in den Anfang jedes Dokuments, das Sie veröffentlichen, damit die Leute, die sich fragen, was zum Teufel sie gerade gelesen haben , dorthin gehen können (anstatt manuelle Betreuer zu belästigen) und den erklärten Fehler finden.

   _{Errata> Fundamentals> Release 2.2> Tippfehler auf Seite 28, zweiter Satz beginnt mit Glück , lesen Sie stattdessen die Sperre .}

Zum Beispiel wären manuelle Betreuer anscheinend an einer vollständigen, genauen Beschreibung der Parallelität und der Sperrung in der formalen Spezifikation interessiert - setzen Sie sie dort ein. Leser von Grundlagen oder fortgeschrittenen Themen könnten an einer Übersicht / Einführung / Anleitung interessiert sein, die aus der Spezifikation extrahiert und auf ihre Bedürfnisse usw. zugeschnitten ist.

_{Es kann hilfreich sein, eine vergleichende Studie der Referenzdokumentation für andere Sprachen wie Ihre zu erstellen. Ziel dieser Studie ist es, die Erfahrungen derjenigen zu nutzen, die sie zuvor gemacht haben, und zu lernen, wie man Fehler vermeidet, die sie gemacht haben.}

_{Last but not least sollten Sie die Dokumentationsentwicklung ähnlich wie die Softwareentwicklung einrichten. Ich meine Dinge wie Versionskontrolle, regelmäßige Veröffentlichungen, Problemverfolgung, Qualitätssicherung usw. Sie möchten vielleicht einige Kompromisse eingehen, wenn sich herausstellt, dass Ihre technischen Redakteure mit solchen Dingen nicht wirklich vertraut sind. Wir wollen keine beschissenen Inhalte "im Austausch" für einen perfekten Entwicklungsprozess bekommen, oder?}

Das erste, was Sie tun müssen, ist das Publikum zu bewerten. Sind Ihre Zielgruppen Linux-Kernel-Hacker oder sind sie Hardware-Designer, die Software-Tools verwenden, um einen Job zu erledigen, aber nicht an Software an sich interessiert sind und keinen CS-Hintergrund haben? Elektrotechniker sind sich wahrscheinlich nicht ganz klar über die Unterschiede zwischen konstanten und nicht konstanten Argumenten, Zeigern auf Objekte und Referenzen usw. Wenn Ihre Grundelemente überladene Namen haben, sollten Sie dieses Konzept besser auf einer für Ihr Publikum geeigneten Ebene erläutern. Das könnte nichts sein, wenn sie C ++ - Programmierer sind.

Das zweite, was Sie bewerten müssen, ist die Granularität der Grundelemente der Sprache. Je feiner die Granularität, desto mehr müssen Sie Anwendungsbeispiele in der Nähe der Syntaxspezifikationen jedes Grundelements bereitstellen. Das heißt, wenn Sie ein Grundelement auf niedriger Ebene haben, das einen bestimmten Kontext instanziiert, und Sie es mit drei anderen Grundelementen auf niedriger Ebene bearbeiten müssen, bevor Sie etwas Nützliches tun können, sollten Sie ein vollständiges Beispiel für eine nützliche Funktion in der Nähe haben. von im Handbuch. In der Online-OpenSL- Dokumentation finden Sie ein hervorragendes Gegenbeispiel für nahezu unbrauchbare Dokumentation.

Stellen Sie sicher, dass Sie alle Nebenwirkungen Ihrer Funktionen erklären .

Wenn Sie nicht möchten, dass die Programmierer Ihres Kunden Sie jeden Abend vor dem Schlafengehen verfluchen, fügen Sie auf jeden Fall viele getestete Beispielcodes hinzu, die einige funktionale Grundelemente auf hoher Ebene ausführen. Stellen Sie sicher, dass die Beispiele nicht nur Codeausschnitte sind, sondern vollständig und kompilierbar oder sofort ausführbar.

Traditionell haben technische Redakteure zwischen Referenzhandbüchern und Benutzerhandbüchern unterschieden . Das Referenzhandbuch enthält normalerweise die Syntaxspezifikationen, eine verständliche Definition der Funktionen oder Grundelemente, eine Diskussion über Gotchas, Leistung und Nebenwirkungen sowie eine kurze Beispielanwendung. Das Benutzerhandbuch enthält ausführlichere Verwendungsbeispiele und eine Diskussion umfassenderer technischer Probleme. Die "C-Programmiersprache" von Kernigan und Ritchie ist ein hervorragendes Gegenbeispiel zu dieser Konvention. Dieser Ansatz funktioniert jedoch nur, wenn die von Ihnen dokumentierte Sprache relativ einfach ist.

Der Autor war von 1987 bis 1991 Leiter der Engineering Services Division im Entwicklungszentrum von Ready Systems Inc. und verantwortlich für die Leitung eines Teams von fünf technischen Redakteuren.