Was ist nützlich in der Dokumentation eines externen Web Service?

Question

Ich habe gerade einen Webservice veröffentlicht und einige ziemlich primitive Dokumentation geschrieben. Ich habe die Eingabeparameter und Ausgabeergebnisse, eine kurze Beschreibung der einzelnen Webdienstmethoden und Beispiele für mögliche Fehler hinzugefügt.

Was ich in meine Dokumentation aufgenommen habe, ist ziemlich genau das, was in der Dokumentation der meisten Webdienste, die ich konsumiert habe, enthalten war. Ich habe mir die Dokumentation von Twitter/Netflix/Amazon angeschaut und einige Ideen, die ich verwenden könnte, um meine zu verbessern, aber ich denke, die Stackie-Community könnte etwas Input liefern.

• Welche Art von „Features“ Web Service-Dokumentation einer Freude machen zu bedienen und ein Web-Service-Verlag mit Missverständnissen zu tun verbringen reduziert auf der Support-Zeit helfen?

• Gibt es Dinge, die Sie in Web- Service-Dokumentation verpassen, die Sie wünschen Sie gehabt?

• Was könnte eine Dokumentation eines Web-Service unschätzbar machen?

Ich weiß, ihr eine Menge Fragen, aber ich versuche, mit einem großen Pinsel zu malen, so viel Feedback zu bekommen, wie ich kann.

Answer 1

Beispiele sind, was es für mich tun. Mein ideales Dokument enthält zahlreiche, klar beschriftete Beispiele, die die grundlegende Funktionsweise der betreffenden Technologie veranschaulichen und auf erweiterte Funktionen hinweisen. Sie müssen nicht unbedingt vollständig sein. Gerade genug, um mir eine Vorstellung davon zu geben, wie das Ding in nützliche Situationen verwendet wird. Darüber hinaus ist eine klare und erschöpfende Beschreibung dessen, was es insgesamt leistet (mit Input, Output und Methoden erklärt), ideal.

Ein gutes Beispiel dafür ist the doc for SQLAlchemy. Es ist in klare Abschnitte unterteilt, die die Aspekte und Stärken des Toolkits beschreiben. In den Abschnitten selbst ist das Dokument mit Inline-Codebeispielen übersät, die Sie durch die grundlegenden Vorgänge führen und Aufschluss darüber geben, wie Sie diese weiterführen würden. Ich habe gestern mit SQLAlchemy angefangen und konnte in kürzester Zeit das Skript schreiben, nach dem ich gesucht habe.

Answer 2

Ich würde mit Evan Meagher zustimmen. Eines der besten Dinge, die Sie tun können, ist die Bereitstellung von Beispielanwendungen, die Ihren Web-Service verwenden. Sie könnten die weltweit beste Benutzerdokumentation schreiben, aber die Leute würden es begrüßen, wenn sie den Beispielquellcode für sich selbst sehen könnten.