Auf dieser Seite finden Sie die Details zu einem Projekt für technisches Schreiben, das für Google Season of Docs angenommen wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- OpenMRS.org
- Technischer Redakteur:
- batbrain7
- Projektname:
- OpenMRS REST API-Dokumentation
- Projektlänge:
- Standardlänge (3 Monate)
Projektbeschreibung
Ich werde meinen Vorschlag in verschiedene Abschnitte unterteilen und der Struktur der Google Maps API- und der GitHub API-Dokumentation folgen.
Zusätzlich dazu möchte ich auch eine Readme-Struktur für die API-Dokumentation vorschlagen, die von realworld.io durchgeführt wird: https://github.com/gothinkster/realworld/tree/master/api.
Ich persönlich fand diese Dokumentation sehr verständlich und einfach zu verwenden.
Mein Vorschlag würde hauptsächlich aus drei Abschnitten bestehen :
Ein Abschnitt, der eine kurze Einführung in die API, zu OpenMRS, zur Verwendung der API und zum weiteren Verlauf enthält.
Wie Sie den API-Schlüssel und die Authentifizierung erhalten, die im Allgemeinen für die API-Anfrage erforderlich sind. Es enthält ein Beispiel für die in der API vorhandenen Authentifizierungstypen sowie die dafür erforderlichen Schlüssel und Werte. Außerdem werden die zulässigen Werttypen für den Schlüssel in diesem Teil aufgeführt. Ein Codebeispiel in einer beliebigen Sprache würde Ihnen helfen, die Header und Antwortformate sowie andere Suchparameter in der API zu schreiben.
Die Antworttypen, die von der API abgerufen werden, die JSON-Typen oder andere Ergebnistypen, die von den APIs zurückgegeben werden, sind erwähnt.
Die verschiedenen API-Routen und welche Parameter zusammen mit diesen gesendet werden müssen, die Header und andere Dinge. Für jede API stehen Codebeispiele in einigen Sprachen zur Verfügung, in denen beschrieben wird, wie die Anfrage beim Schreiben des Codes dafür gestellt wird. Abgesehen von den allgemeinen Fehlercodes, die bei jeder API auftreten können, sollten ebenfalls erwähnt werden.
Das ist eine allgemeine Vorstellung davon, wie die Dokumentation für die REST API definiert wird.
Der Zeitplan für das Projekt sieht so aus :
1. August bis 1. September
Machen Sie sich mit meinem Mentor vertraut und besprechen Sie im Detail, welche Dokumentationsstufe in verschiedenen Teilen der Codebasis erforderlich ist. Besprechen Sie auch, wie detailliert die Low-Level- und die High-Level-Dokumentation sein sollten. Außerdem werde ich mir die Codebasis ansehen und die Konzepte studieren, damit ich sie besser dokumentieren kann.
Woche 1 und 2
Ich werde den Leitfaden für Mitwirkende aktualisieren und erweitern. Ich werde die Dokumentation zum Erstellen des Quellcodes verbessern. Außerdem füge ich einen Abschnitt für Dokumentare hinzu, in dem erklärt wird, wie neue Mitwirkende bei der Dokumentation helfen können. Ich werde die verschiedenen API-Dokumente studieren und mit der Einführung beginnen und die Authentifizierung für die API hinzufügen.
Woche 3–8
Ich füge die API-Routen und ‑Antworten sowie einige Codebeispiele für jeden API-Typ hinzu. Es kann ähnliche API-Typen geben.
Woche 9 und 10
Strukturieren Sie die API-Dokumentation mithilfe von Links, z. B. einem verknüpften Index für lange API-Dokumentation, und unterteilen Sie sie weiter nach anderen Kriterien wie Codeabschnitten, Übersicht, Parametern und Stammendpunkten.
Letzte Woche
In der letzten Woche werde ich meinen Abschlussbericht über die Arbeit vorbereiten, die ich in den 12 Wochen der Dokumentation geleistet habe. In der Zwischenzeit überprüfe ich die Dokumentation und füge sie gegebenenfalls fehlende Informationen hinzu.