50 Dokumentationsfragen

Published on November 29, 2018

50 Dokumentationsfragen

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

    Wir machen Produkte einfacher Software für Raketen, aber technisch immer noch komplex. Wir sind sehr bemüht, die Benutzeroberflächen der neuen Versionen zu vereinfachen, stellen jedoch fest, dass es immer einen Benutzer geben wird, der etwas nicht versteht und auf die Dokumentation eingeht. Daher sollte das Dock nützlich und praktisch sein, um den Eindruck des Produkts nicht zu beeinträchtigen.

    Wir haben sechs Produkte, deren Dokumentation von Anfang an von den Entwicklern geschrieben wurde. Seit einem halben Jahr schreiben wir alte und neue Artikel um.. Unter dem Strich - 50 Fragen, die uns dabei helfen, es gut zu machen. Aber zuerst eine kleine Einführung.



    Warum Dokumentation wichtig ist und wer sollte das tun?


    Ein gutes Dock zu bauen ist schwierig. Irgendwo darauf arbeitet eine riesige Abteilung von Analysten, Schriftstellern und Redakteuren, und irgendwo schreiben die Entwickler an das Dock (hat - beschrieben).

    Wir haben zwei technische Redakteure für sechs Produkte mit mehreren Versionen. Dies ist nicht genug, daher arbeiten Produktmanager, Tester, First-Line-Support und Marketing am Dock. 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. Zusammen machen wir das Dock besser.

    Wenn Sie eine kleine Abteilung von Technikern haben, ziehen Sie Mitarbeiter aus anderen Abteilungen an. Wenn sie nicht interessiert sind, führen Sie die folgenden Argumente auf. Erster unterstützter, zweiter und dritter Vermarkter und Produkt. 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 lösen, ohne sich an den Support zu wenden. Der verbleibende Support wirft einen Link zu den Anweisungen oder geht ihn schnell selbst durch. Die vollständige Dokumentation kann zum Erstellen von Chat-Bots verwendet werden. All dies verkürzt die Reaktionszeit auf Kundenanfragen, erhöht deren Zufriedenheit und senkt die Supportkosten.
    2. Faktor der Wahl . Die Dokumentation beeinflusst die Wahl des Kunden zusammen mit dem Preis, der Bequemlichkeit und der Funktionalität. Dies wird durch unsere Untersuchungen und Rückmeldungen von ISPmanager- und DCImanager-Benutzern bestätigt . In diesem Sinne ist das Dock kein Bedarf an Unterstützung mehr und wird zu einem Wettbewerbsvorteil im Marketing.
    3. Loyalitätsfaktor . Wenn der Client das Dock zu Beginn oder während des Vorgangs nicht verstanden hat, ist dies ein Problem. Einen Kunden zu gewinnen ist zu teuer, um wegen schlechter Artikel zu verlieren.

    Wie man eine gute Dokumentation macht


    Definieren Sie das Ziel . Das ist der größte Schmerz. Es ist nicht das Ziel, eine Funktion nur zum Zwecke der Beschreibung oder des Kommentars auf der Benutzeroberfläche zu beschreiben. Ein Ziel ist immer eine nützliche Aktion. Was sollten Benutzer, Administratoren oder Entwickler nach dem Lesen des Artikels wissen und können? Erstellen Sie beispielsweise eine Website und verknüpfen Sie eine Domain mit dieser, stellen Sie ein SSL-Zertifikat aus, richten Sie Sicherungen ein usw. Das heißt, lösen Sie Ihr Problem.

    Kennen Sie das Publikum . Wir unterteilen Kunden in Benutzer, Administratoren und Entwickler. 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 auf das richtige Thema prüfen, Anrufe in der ersten Zeile abhören, die Website und den Blog anzeigen (Marketing schreibt auch die richtigen Dinge). Und erst danach anfangen zu schreiben.

    Überprüfen, bearbeiten und erneut prüfen. Technische Redakteure sollten die Erstprüfung durchführen. Nach ihr noch einer. Dann lohnt es sich, Support, Marketing und andere Abteilungen auf den Prüfstand zu stellen. Dann müssen Sie mit dem Handbuch über Stil und Design überprüfen - redpolitikoy. Jemand von der Seite oder ein anderer Techniker ließ ihn die letzte Lesung machen. Wenn Sie einen Redakteur haben, wird er diese Phase übernehmen.
    Über redpolicy
    Редполитика оговаривает стиль изложения (формальный или неформальный), вёрстку и дизайн (скриншоты, их размеры, стили таблиц, списки), а также спорные вопросы (е или ё, написание терминов). Если у вас ещё нет такого документа, обязательно сделайте, он сокращает время и наводит порядок. Для вдохновения и понимания посмотрите доклад с конференции Яндекса и примеры руководств IBM или Mailchimp.

    Verbreiten 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 Sie, beziehen Sie sich auf das Produkt, geben Sie es dem Marketing, dem Support. Schreiben Sie nicht an den Tisch.

    50 Fragen für die Arbeit am Dock


    Bei der Arbeit an der Dokumentation haben wir dieselben Fehler wiederholt. Sie verbrachten zu viel Zeit damit, die Artikel zu überprüfen, und der Leitfaden, der von Anfang an ein Allheilmittel zu sein schien, half nicht, weil das Problem in der Herangehensweise und im Inhalt lag. Damit sich Tech-Autoren den Artikel schnell selbst einfallen lassen können, haben wir alle Fragen in eine Liste aufgenommen, die wir ihnen ständig gestellt haben (oder vergessen haben, sie zu stellen). Verwenden Sie diese Option, wenn Sie auch in das 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 er (zu erledigende Arbeiten)? Gibt es eine Beschreibung der Person?
    3. Wie ist der Ausbildungsstand dieses Benutzers? Was weiß er schon? Was ist ihm nicht klar?
    4. Wie können Sie dies einem Anfänger erklären und den Fortgeschrittenen nicht durch Erklären elementarer Dinge stören?
    5. Was sollte dem Benutzer sonst noch erklärt werden, damit er den Hauptinhalt des Artikels versteht?
    6. Welcher Abschnitt der Dokumentation ist für diesen Artikel geeignet?
    7. Soll dieser Artikel oder ein Teil davon in anderen Abschnitten vervielfältigt werden?
    8. Auf welche Artikel soll ich verweisen?
    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 nun, was zu tun ist?
    12. Hat die Marketingabteilung in diesem Blog Artikel und Neuigkeiten zu diesem Thema verfasst? Können sie den Wortlaut, die Struktur usw. "einsehen"?
    13. Gibt es auf der Website Abschnitte zu diesem Thema?
    14. Was haben die Benutzeroberfläche und der Produktmanager in das Skript eingefügt? Warum hat es das getan?
    15. Wie wird diese Frage von Wettbewerbern beschrieben?
    16. In welchen Bereichen sehen Sie noch die besten Praktiken?

    Inhaltsprüfung


    17. Wurde das Ziel des Artikels erreicht?
    18. Wird ein fortgeschrittener Benutzer alles verstehen?
    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? Wird der Benutzer in der Lage sein, das Ziel zu erreichen, wenn er nur diese Anweisung befolgt?
    22. Wir haben alle Fälle / Pfade des Benutzers berücksichtigt?
    23. Passt der Artikel in den ausgewählten Bereich?

    Schriftsatz


    24. Gibt es unlesbare Textbögen? Ist es möglich, die Schaltung zu ersetzen?
    25. Gibt es lange Absätze?
    26. Sind die Absätze zu kurz?
    27. Gibt es zu lange Listen?
    28. Gibt es zu verschachtelte, schwer lesbare Listen (mit mehr als zwei oder drei Ebenen)?
    29. Bilder genug?
    30. Bilder sind nicht zu viele? Illustrieren wir zu offensichtliche Schritte?
    31. Wenn es Pläne gibt, sind sie klar?
    32. Tabellen sind nicht schwer für die Wahrnehmung?
    33. Sieht die Seite im Allgemeinen gut aus?

    Literarische Bearbeitung


    34. Alles ist in der Anleitung dekoriert?
    35. Entspricht der Stil des Restes der Dokumentation?
    36. Haben Sie Vorschläge, die Sie vereinfachen können?
    37. Gibt es komplizierte Begriffe, die einer Erklärung bedürfen?
    38. Haben Sie Angestellte?
    39. Hast du eine Wiederholung?
    40. Tut es deinen Ohren nicht weh?

    Endgültiges Korrekturlesen


    41. Gibt es Tippfehler, Rechtschreibfehler und Satzzeichen?
    42. Mit Silbentrennung, Absätzen und Abschnitten ist alles in Ordnung?
    43. Alle Bilder sind signiert?
    44. Sind die Schnittstellenelemente richtig benannt?
    45. Gibt es überall Links? Sie arbeiten und führen wo nötig?

    Sofort nach Veröffentlichung


    46. ​​Der Artikel hat Abschnitte, die in anderen Artikeln "aufholen"? Sind sie mit Makros verziert, damit Änderungen in einem Artikel automatisch auf andere übertragen werden?
    47. Soll ich auf diesen Artikel aus anderen Abschnitten verweisen? Wenn ja, welche?
    48. Soll ich dem Produkt einen Schnelllink zu diesem Artikel hinzufügen?
    49. Muss ich einen Link an den Support, das Marketing oder andere Abteilungen senden?
    50. Muss ich einen Artikel zur Übersetzung einreichen?

    Diese Liste kann ausgedruckt und auf den Desktop gestellt oder an die Wand gehängt werden. Oder verwandeln Sie sich in eine Checkliste. Ein Teil der Fragen kann in den Geschäftsprozess eingebracht werden. Unsere ist zum Beispiel im gesamten Entwicklungsprozess in YouTrack festgelegt. Die Dokumentationsaufgabe durchläuft verschiedene Phasen und Abteilungen. Ohne schriftliche Dokumentation können Sie einem Release keine Funktion zuweisen.