Obwohl das zweite Treffen von Write the Docs in Moskau vor einem Monat stattfand, ist es nie zu spät, einen Bericht und kurze Zusammenfassungen von Berichten zu veröffentlichen. Es ist uns gelungen, praktisch alles zu diskutieren: von der Dokumentation einer RESTful-API bis hin zu professionellen Entwicklungen eines technischen Redakteurs.
Mitap brachte übrigens nicht nur das „technische Ghetto“ zusammen, sondern auch eine Vielzahl anderer Spezialisten, die auf die eine oder andere Weise mit der Dokumentation des Projekts arbeiten: Teamleiter, Analysten, Tester und sogar einen technischen Direktor.
Unser
Treffen fand am 14. Oktober , Sonntag, statt (er gab die häufigsten Fragen zu ihm an: „Warum am Sonntag?“) Im IPONWEB-Büro. Die Write the Docs-Kundgebungen finden auf der ganzen Welt statt, von Bangalore bis San Francisco, von London bis Seoul. Der russische Zweig der Gemeinde gewinnt nur an Aktivität, aber es gibt bereits Niederlassungen in Moskau, St. Petersburg und Nowosibirsk.
Anton Telin, Warum und wie wir Videoanweisungen machenVideoFolienAnton leitet die Abteilung für technische Dokumentation bei VLSI, die ein elektronisches Dokumentenmanagementsystem herstellt. Warum ein Video? Die Leute wollen keine Anweisungen lesen, sie wollen ein Problem lösen. Die Menschen wollen ihnen klar und deutlich erklärt werden.
Video ist eine bequeme Möglichkeit, eine große Menge an Informationen zu präsentieren, ein Skript in Dynamik und eine Abfolge von Aktionen zu implementieren. Sie können die Aufmerksamkeit des Benutzers auch mit Musik oder Synchronisation betonen.
Wenn das Produkt komplex ist und keine gut durchdachte Oberfläche hat, ist es ohne den visuellen Teil schwierig, dem Benutzer seine Essenz zu vermitteln. Das Plus ist, dass es die Kosten für technischen Support reduziert.
Nachteile - nicht für alle Veröffentlichungsformate geeignet, es ist schwierig, sie in doc und pdf einzubetten. Es ist schwer, danach zu suchen. Hochwertige Videos sind teurer.
Ein weiteres dringendes Problem ist die Komplexität des Updates, aber Antons Kampagne hat dieses Problem gelöst. Sie weigerten sich, Screencasts (Screenshots) zugunsten hochwertiger Screenshots aufzunehmen.
Das Unternehmen verwendet zwei Videoformate:
1. Die Videoanweisung ist eine Abfolge von Aktionen im Detail und in Schritten. Dauer ~ 2 Minuten. 1 Anweisung ist 1 Problem. Es geht nicht um alle Fenster, Dohlen, Knöpfe. Dann wurden Synchronisation, Hintergrundmusik, Texterklärungen und Untertitel hinzugefügt.
2. Erklärendes Video. Dies ist etwas an der Schnittstelle von Produktanweisung und Präsentation. Eine allgemeine Ansicht ohne technische Details löst verschiedene Probleme oder Szenarien. Dieses Video kann Personen und Animationen enthalten. Dauer 2-3 Minuten.
Tools: Adobe Premiere und Adobe After Effect zum Bearbeiten, Adobe Audition für Sound, Photoshop und Snagit zum Bearbeiten von Bildern. Das Projekt besteht aus einer Vielzahl von Screenshots, die nicht relevant oder fehlerhaft sind und dann leicht zu ersetzen sind. Als nächstes zeichnen Sie die Bewegung der Maus, Animation, Ton.
Sie beschlossen, nicht professionelle Ansager zum Überspielen zu verwenden, da sie zu förmlich klangen, und verwendeten daher die Stimme eines Mitarbeiters des Unternehmens, Ilya, der in einer Metalcore-Gruppe singt. Nach einem Informationsblock wird notwendigerweise eine Pause von 2 Sekunden zum Verständnis gegeben.
Die Videos werden sowohl auf Ihrem eigenen Hosting als auch auf Youtube veröffentlicht. Der Nachteil ist, dass es von vielen Unternehmen aus Sicherheitsgründen blockiert wird.
Natürlich sammelt VLSI alle verfügbaren Statistiken: durchschnittliche Anzeigezeit, Likes, Anrufe des technischen Supports, die über den Videolink geschlossen wurden.
Nikolay Volynkin, Technischer Redakteur Version 2.0.1VideoFolienDies ist eine Wiederholung oder besser gesagt eine Ergänzung des Berichts der SECR-Konferenz. Nikolai beobachtete lange Zeit technische Redakteure und bemerkte, dass sie nicht immer wissen, wie sie ihre Vorteile rechtfertigen und messen können, und die Führungskräfte, die ihnen auch Aufgaben stellten.
Es gibt einige verwandte Aufgaben, die technische Redakteure lösen könnten. Nikolay sagte, welche Karrierewege und Fähigkeiten technische Beschreibungen haben, wie Sie Ihre neuen Aufgaben an das Unternehmen verkaufen können.
5 Rollen, die ein technischer Redakteur spielen kann:
1.
Docops - Entwickler für Dokumentation, ein Autor / Programmierer, der die Erstellung, Überprüfung und das Hochladen von Dokumentation automatisieren kann, das Team darin schult, damit zu arbeiten, und alle Prozesse um ihn herum neu erstellt.
Die Vorteile sind weniger manuelle Arbeit, Ressourceneinsparungen und höhere Bereitstellungsgeschwindigkeiten.
2.
UX Writer - ein Spezialist für das Schreiben von Texten in Schnittstellen.
Vorteile - Designer, Gedichte, Analysten oder Front-End-Entwickler verstehen nicht immer, wie man richtig schreibt, wie man Funktionen, Schaltflächen und Übergänge an den Benutzer übermittelt. Die Texte werden nach dem Prinzip geschrieben, wer zuerst aufgestanden ist und Hausschuhe. Bequeme Benutzeroberfläche, wodurch die Zeit für technischen Support verkürzt wird.
3. Als
technischer Evangelist spricht er über Technologie, interagiert mit der Gemeinschaft, gestaltet sie.
Vorteile - erhöhtes Vertrauen und Loyalität gegenüber dem Unternehmen, dem Produkt, Vereinfachung der Einstellung, HR-Marke.
4.
Knowledge Manager - Untersucht, wie ein Unternehmen Wissen produziert, speichert und überträgt. Richtet diese Prozesse ein, damit kein Wissen verloren geht.
Vorteile - reduzierter Busfaktor, Anpassungsgeschwindigkeit der Mitarbeiter, sowohl für Anfänger als auch bei Übergängen innerhalb, Wiederverwendung von Wissen, Risikominderung.
5.
Dokumentationsinhaber - PM und Dokumentationsanalyst. Er baut das gesamte System der Kommunikation und Benutzerinteraktion in der Dokumentation auf.
Der Vorteil liegt wiederum in der Senkung der Supportkosten.
Während der Diskussion haben wir an eine solche integrierte Rolle als Content Manager erinnert, die im Bericht nicht erwähnt wurde.
Konstantin Valeev, FoliantVideoFolienConstantine von Restrim sprach über das
Foliant- Tool - die Implementierung eines Docops-Workflows basierend auf der Markdown-Sprache. Vor einem Jahr hat Konstantin im Rahmen des
Mini-Hyperbatons in Yandex bereits über Foliant gesprochen, und seitdem hat sich viel geändert.
Die Dokumentation ist in MD-Dateien geschrieben und befindet sich an verschiedenen Stellen. Das Tool unterstützt die kontinuierliche Integration und die automatische Montage und ermöglicht es Ihnen, MD nach Ihren Wünschen zu erweitern.
Anforderungen: Sie müssen docx für Kunden und PDF mit guter Typografie bereitstellen und über lesbare Quellen (nicht XML) verfügen.
Unter der Haube wird ein universeller Pandoc-Konverter verwendet, Python, Bash-Skripte sind oben aufgewickelt. Mit der Zeit wuchs jedoch die Anzahl der Skripte, sodass sie in eine einzige monolithische Anwendung umgeschrieben wurden.
Aus dem Monolithen bildeten sie dann eine modulare Struktur, wobei der Kernel die Baugruppe kontrollierte, Präprozessoren, die die MD für die Arbeit der Assembler konvertieren, und die Assembler selbst.
Foliant ist im Wesentlichen der Klebstoff zwischen guten Werkzeugen (mkdoc, pandoc, Schiefer, Latex). Jetzt versuchen sie zu lehren, wie Dokumentationsquellen aus verschiedenen Formaten verwendet werden.
Im Projektordner befindet sich eine Konfiguration mit der Struktur des endgültigen Dokuments, der Stile und der tatsächlichen MD-Dateien. Die Präprozessoren nehmen dann die Quell-MD-Dateien und wenden die Verarbeitung auf sie an, um die gewünschte MD im Stil von all.md (md im Foliant-Stil) zu erstellen, und sammeln dann die resultierenden Dokumente ( pandoc, mkdoc) machen sie zu Zielen (Dokumenten). Nach der MD-Assembly werden Linters ausgeführt, um die Syntax zu überprüfen. Build-Benachrichtigungen über Builds oder Fehler werden ebenfalls gesendet.
All dies kann in Docker gesammelt werden, sodass alle Pakete auf eine Weise und nicht einzeln geliefert werden.
Foliant unterstützt Advanced Include, kann Codeteile aus Gitlab / Github und Bilder mit Layouts aus Simpli extrahieren, Diagramme zeichnen, Parameter im Text ersetzen, bedingte Anweisungen.
Nikita Samokhvalov, Umfassende Dokumentation zur RESTful-APIVideoFolienNikita Samokhvalov, Technischer Direktor von Notamed, erklärte, wie die Generierung der API-Dokumentation basierend auf Open API 3.0 konfiguriert wurde.
Wie alle anderen haben sie mit Google Text & Tabellen begonnen, aber es gibt weder eine Versionierung noch die Möglichkeit, Zweige zu erstellen. Dann haben sie gerade angefangen, MD-Dateien in das Repository zu schreiben, das Problem der Versionierung und Erstellung von Zweigen wurde gelöst, aber alles war langsam. Dann kam zur automatischen Erzeugung.
Die Dokumentation hatte die folgenden Anforderungen: Vererbung und Wiederverwendung von Dokumentationen, die Möglichkeit, einen Link zu Beschreibungen von Parametern und Methoden bereitzustellen, Informationen zur Unterscheidung von Zugriffsrechten, Dokumentation als Code (synchrone Bereitstellungen und Änderungen). Darüber hinaus wird die Dokumentation nicht öffentlich veröffentlicht, sondern nur für Ihr Team und Ihre Entwicklungsteams.
Wir haben uns für die OpenAPI 3.0-Spezifikation entschieden. Warum? Es ist das frischeste, es unterstützt mehr Funktionen, obwohl es immer noch ein kleines Ökosystem und Fachwissen gibt.
Sie nahmen das
Shins- Tool (zeigt MD-Dateien auf einer schönen Landingpage mit Beispielen für Abfragen, Beschreibung von Methoden, Parametern),
Widdershins (yaml / json zu MD-Konverter), sie schrieben auch ihr eigenes
Specker- Paket (installiert alle notwendigen Abhängigkeiten, arbeitet mit npm, prüft auch die Richtigkeit der Dateizuordnungsstruktur).
Das Einrichten der Umgebung und das Zusammenstellen der Dokumentation erfolgt in einer einzelnen Zeile in der Konsole. Dateien, die in jedem Projekt wiederverwendet werden müssen, z. B. eine Berechtigungsbeschreibung, fallen in den Ordner dependencies /.
Nikita sprach auch darüber, wie sie mit Niederlassungen in einem verteilten Team arbeiten, wenn die Aufgabe darin besteht, die Dokumentation zu aktualisieren, und natürlich über die Fallstricke und Schwierigkeiten, die mit der Implementierung von OpenAPI 3.0 einhergingen.
Svetlana Novikova, Wissensmanagement unter Verwendung der KompetenzmatrixVideoFolienSvetlana (übrigens, das bin ich) sprach darüber, wie sie im Unternehmen einen Neustart des End-to-End-Instruments aus dem Bereich Personalmanagement als Kompetenzmatrix arrangiert haben, wie das Wissensmanagement auf diese Weise eingesetzt wird, wie das Instrument zur Reduzierung des Busfaktors beiträgt, es besser ist, Neuankömmlinge einzusteigen und sogar Teile zu finden Code für das Refactoring.
Danila Medwedew, NeuroCodeVideoDanila sprach über ein Tool namens NeuroCode, das für alle verständlich ist und möglicherweise unserer Zeit voraus ist, um Wissen zu modellieren und zu speichern.
Dieses Tool ist für alle nützlich, die am Entwurf von IT-Systemen beteiligt sind. Danila schlägt insbesondere vor, dokumentbasierte Systeme aufzugeben. Jedes System wird als Netzwerk betrachtet, gemäß dessen Knoten einige Informationen übertragen werden. Alle Elemente des Systems befolgen dieses Prinzip - Push-Updates, Dokumentübertragung, Feedback-Übertragung. Der Zweck des NeuroCodes besteht darin, „unproduktive Kosten für die Unterstützung von Prozessen zu reduzieren und die kollektive Intelligenz der Organisation zu stärken“.
Das NeuroCode-Projekt entstand aus der Lösung des Problems - wie man ein gutes Informationsarchiv für ein Team oder für sich selbst erstellt, wie man ein Informationsmodell erstellt. Der Prototyp des Systems ist hergestellt und funktioniert, jetzt wird es mit Hilfe von Systemingenieuren und Geschäftsarchitekten getestet. Das System verfügt über eine skalierbare Schnittstelle und basiert auf einer fraktalen Datenstruktur. Es basiert auch auf den Ideen von Douglas Engelbart (dies ist einer der ersten Forscher an der Mensch-Maschine-Schnittstelle, dem Autor der Konzepte von GUI, Hypertext usw.) der 1960er Jahre über Open Hyper-Document Systems (OHS), als das System nicht dokumentenbasiert, sondern ein einziges ist Das heißt, es implementiert alle Prozesse menschlicher Aktivität.
PS Im Allgemeinen sollten Sie sich das Video besser ansehen.
Das nächste Treffen,
Write the Docs Moscow, findet am 7. Dezember im Büro von Positive Technologies statt und wird im Format Positive Authoring Tools Battle abgehalten.
