50 Fragen zur Bearbeitung der Dokumentation

Unabhängig davon, wie sehr sich der UX-Designer bemüht, kann eine Person von der Straße die Steuerungsschnittstelle des Raumfahrzeugs nicht ohne einen Hinweis herausfinden. Und nicht einmal von der Straße. Nur weil die Rakete groß ist und es viele Einstellungen gibt.

Wir machen Produkte einfacher als Software für Raketen, aber dennoch technisch anspruchsvoll. Wir bemühen uns sehr, dass die Schnittstellen der neuen Versionen einfach sind, aber wir erkennen, dass es immer einen Benutzer geben wird, der etwas nicht versteht und zur Dokumentation geht. Daher sollte es ein Dock geben, und um den Eindruck des Produkts nicht zu beeinträchtigen, sollte es nützlich und bequem sein.

Wir haben sechs Produkte, deren Dokumentation von Anfang an von Entwicklern verfasst wurde. Seit einem halben Jahr schreiben wir alte und neue Artikel um . Unter dem Schnitt - 50 Fragen, die uns dabei helfen, dies gut zu machen. Aber zunächst eine kleine Einführung.

Warum Dokumentation wichtig ist und wer sie tun sollte

Ein gutes Dock zu bauen ist schwer. Irgendwo arbeitet eine riesige Abteilung von Analysten, Autoren und Redakteuren daran, und irgendwo schreiben Entwickler an das Dock (fertig - beschrieben).

Wir haben zwei technische Redakteure für sechs Produkte mit mehreren Versionen. Dies ist nicht genug, so dass Produktmanager, Tester, die erste Linie der Support- und Marketingarbeit am Dock arbeiten. Sie schreiben keine Artikel, helfen aber dabei, das Produkt und die Aufgaben des Kunden zu verstehen, ein Thema auszuwählen und Informationen zu sammeln, den Inhalt und das Design des fertigen Artikels zu überprüfen. Gemeinsam machen wir das Dock besser.

Wenn Sie eine kleine Techwriter-Abteilung haben, stellen Sie Mitarbeiter aus anderen Abteilungen ein. Wenn sie nicht interessiert sind, geben Sie Argumente aus der folgenden Liste an. Erster Support, zweites und drittes Marketing und Produktmarketing. Warum ist Dokumentation wichtig?

1. Unterstützungsfaktor . Der erste und offensichtlichste der Gründe. Wenn die Dokumentation gut ist, können die meisten Kunden das Problem beheben, ohne den Support zu kontaktieren. Die verbleibende Unterstützung wird einen Link zu den Anweisungen werfen oder diese schnell selbst durchgehen. Mit der vollständigen Dokumentation können Chat-Bots erstellt werden. All dies verkürzt die Reaktionszeit auf Kunden, erhöht deren Zufriedenheit und senkt auch die Supportkosten.
2. Auswahlfaktor . Die Dokumentation beeinflusst die Wahl des Kunden sowie den Preis, die Bequemlichkeit und die Funktionalität. Dies wird durch unsere Forschung und das Feedback von ISPmanager- und DCImanager-Benutzern bestätigt . In diesem Sinne ist das Dock keine Notwendigkeit der Unterstützung mehr, sondern wird zu einem Wettbewerbsvorteil, der Teil des Marketings ist.
3. Loyalitätsfaktor . Wenn der Client das Dock zu Beginn oder während des Vorgangs nicht verstanden hat, ist dies ein Problem. Die Gewinnung eines Kunden ist zu teuer, um aufgrund schlechter Artikel zu verlieren.

Wie man eine gute Dokumentation macht

Definieren Sie ein Ziel . Das ist der größte Schmerz. Es ist nicht das Ziel, eine Funktion nur zur Beschreibung oder zum Kommentieren einer Benutzeroberfläche zu beschreiben. Ein Ziel ist immer eine nützliche Handlung. Was sollte ein Benutzer, Administrator oder Entwickler wissen und lesen können, nachdem er einen Artikel gelesen hat? Erstellen Sie beispielsweise eine Site und binden Sie eine Domain daran, stellen Sie ein SSL-Zertifikat aus, konfigurieren Sie Sicherungen usw. Lösen Sie also Ihr Problem.

Kennen Sie das Publikum . Wir teilen Kunden in Benutzer, Administratoren und Entwickler ein. Dies reicht jedoch nicht aus, um nützliche Texte zu erstellen. Um das Publikum schnell zu verstehen, können Sie zu UX und dem Produkt gehen, Supportanfragen und deren Antworten zum Thema studieren, Erstanrufe anhören, sich die Website und den Blog ansehen (Marketing schreibt auch die notwendigen Dinge). Und erst danach fangen Sie an zu schreiben.

Überprüfen, bearbeiten und erneut prüfen . Technische Redakteure sollten eine erste Überprüfung durchführen. Nach ihr noch eine. Dann lohnt es sich, Support, Marketing und andere Abteilungen mit dem Audit zu verbinden. Dann müssen Sie mit dem Stil- und Designhandbuch - Redaktionsrichtlinien überprüfen. Jemand von der Seite oder ein anderer Tech-Autor ließ ihn das endgültige Korrekturlesen durchführen. Wenn Sie einen Redakteur haben, wird er diese Phase übernehmen.

Verteilen Sie den Artikel nach der Veröffentlichung . Wenn die Dokumentation geschrieben ist, braucht sie höchstwahrscheinlich jemand. Zeigen Sie es dem Licht und nutzen Sie es maximal: Übersetzen, auf das Produkt verweisen, es dem Marketing geben, Support. Schreiben Sie nicht auf den Tisch.

50 Fragen zur Arbeit am Dock

Bei der Arbeit an der Dokumentation haben wir die gleichen Fehler wiederholt. Sie verbrachten zu viel Zeit damit, die Artikel zu überprüfen, und der Leitfaden, der anfangs wie ein Allheilmittel schien, half nichts, da das Problem in der Herangehensweise und im Inhalt lag. Damit die technischen Redakteure den Artikel schnell und schnell in den Sinn bringen können, haben wir alle Fragen, die wir ihnen ständig gestellt (oder vergessen haben), in einer Liste zusammengefasst. Verwenden Sie diese Option, wenn Sie auch ein Dock schreiben.

Ziele

1. Für wen schreibe ich einen Artikel? Wer ist der zukünftige Leser: Benutzer, Administrator, Entwickler?
2. Vor welchen Aufgaben steht es (zu erledigende Aufgaben)? Gibt es eine Beschreibung der Person?
3. Wie ist der Ausbildungsstand dieses Benutzers? Was weiß er schon? Was ist ihm nicht klar?
4. Wie kann ich dies einem Anfänger erklären und gleichzeitig die fortgeschrittene Erklärung grundlegender Dinge nicht verärgern?
5. Was muss dem Benutzer noch erklärt werden, damit er den Hauptinhalt des Artikels versteht?
6. Für welchen Abschnitt der Dokumentation ist dieser Artikel geeignet?
7. Sollte dieser Artikel oder ein Teil davon in anderen Abschnitten dupliziert werden?
8. Auf welche Artikel soll ich verlinken?
9. Vielleicht sollte dieser Artikel von einer Videoanweisung begleitet werden?

Informationsquellen

10. Haben aktuelle Benutzer Probleme mit dem Thema des Artikels?
11. Wie erklärt der Support jetzt, was zu tun ist?
12. Hat die Marketingabteilung Blog-Artikel und Neuigkeiten zu diesem Thema geschrieben? Können sie ihren Wortlaut, ihre Struktur usw. ausspionieren?
13. Gibt es auf der Website Abschnitte zu diesem Thema?
14. Was enthielt das Skript die UX und den Produktmanager? Warum hat es das getan?
15. Wie wird diese Frage von Wettbewerbern beschrieben?
16. In welchen Bereichen können Sie noch die Best Practices sehen?

Inhaltsprüfung

17. Haben Sie das Ziel des Artikels erreicht?
18. Wird einem fortgeschrittenen Benutzer alles klar sein?
19. Wird einem Anfänger alles klar sein?
20. Ist alles logisch und konsistent? Keine Sprünge und Abgründe?
21. Ist die Reihenfolge der Aktionen korrekt? Kann der Benutzer das Ziel erreichen, indem er nur diese Anweisung befolgt?
22. Haben wir alle Fälle / Benutzerpfade berücksichtigt?
23. Passt der Artikel in den ausgewählten Abschnitt?

Layoutprüfung

24. Gibt es unlesbare Textblätter? Ist es möglich, die Schaltung auszutauschen?
25. Gibt es lange Absätze?
26. Gibt es zu kurze Absätze?
27. Gibt es zu lange Listen?
28. Gibt es Listen, die für die Wahrnehmung zu kompliziert sind (solche, in denen es mehr als zwei oder drei Ebenen gibt)?
29. Gibt es genug Bilder?
30. Nicht zu viele Bilder? Illustrieren wir zu offensichtliche Schritte?
31. Wenn es Schemata gibt, sind sie verständlich?
32. Tabellen sind nicht schwer für die Wahrnehmung?
33. Sieht die Seite insgesamt gut aus?

Literarische Bearbeitung

34. Ist alles nach dem Leitfaden gestaltet?
35. Ist der Stil der restlichen Dokumentation konsistent?
36. Irgendwelche Vorschläge, die vereinfacht werden können?
37. Gibt es komplexe Begriffe, die einer Klärung bedürfen?
38. Gibt es einen Klerikalismus?
39. Gibt es eine Wiederholung?
40. Verletzt nichts Ihr Gehör?

Endgültiges Korrekturlesen

41. Gibt es Tippfehler, Rechtschreib- oder Interpunktionsfehler?
42. Sind Bindestriche, Absätze und Abschnitte in Ordnung?
43. Sind alle Bilder signiert?
44. Sind die Schnittstellenelemente korrekt benannt?
45. Gibt es überall Links? Arbeiten sie und wohin gehen sie?

Sofort nach Veröffentlichung

46. ​​Enthält der Artikel Abschnitte, die in andere Artikel „gezogen“ werden? Sind sie mit Makros dekoriert, sodass Änderungen in einem Artikel automatisch auf andere angewendet werden?
47. Sollte auf diesen Artikel aus anderen Abschnitten verwiesen werden? Wenn ja, von welchen?
48. Müssen Sie dem Produkt einen Schnelllink zu diesem Artikel hinzufügen?
49. Muss ich den Link an Support, Marketing oder andere Abteilungen senden?
50. Muss ich einen Artikel zur Übersetzung einreichen?

Diese Liste kann gedruckt und auf den Desktop gestellt oder an die Wand gehängt werden. Oder verwandeln Sie sich in eine Checkliste. Einige der Fragen können in den Geschäftsprozess einbezogen werden. Unsere ist beispielsweise im allgemeinen Entwicklungsprozess in YouTrack festgelegt. Die Aufgabe der Dokumentation durchläuft verschiedene Phasen und Abteilungen. Ohne schriftliche Dokumentation können Sie keine Funktion zum Freigeben angeben.