Normalerweise gibt es ein Problem mit der Wissensdatenbank des Unternehmens für Entwickler - sie wird entweder zu einer Leere, weil es keine Motivation gibt, sie entweder mit einer verantwortlichen Person zu füllen, oder auf einen Balkon, der mit Dingen aus einer sowjetischen Wohnung gefüllt ist. Jeder trägt dazu bei, aber sie schreiben zufällig, die Informationen werden schnell veraltet und Es hat nicht immer Zeit zum Aktualisieren.
Wie kann dies vermieden oder zumindest mögliche Kosten gesenkt werden? Wie machen Sie Ihre Unternehmensbasis warm und lampenartig? Ich werde versuchen zu antworten.
Dokumentation zum Kollaborationsstil
Es gibt einen solchen Ansatz, eine kollaborative Dokumentation, die ursprünglich im Bereich der Medizin erschien, als die Entscheidung, eine Diagnose zu stellen, gemeinsam vom Patienten und mehreren Ärzten getroffen wird.
Ein eindrucksvolles Beispiel im Bereich IT sind Google Text & Tabellen, Wiki, Github, jedes System mit internen Konventionen und der Fähigkeit, an einem Projekt zusammenzuarbeiten.
Die Idee ist, Entwickler, Experten und Kritiker so früh wie möglich in die Arbeit an der Dokumentation einzubeziehen, um Lücken zu identifizieren.
Warum ist das überhaupt notwendig?
Erstens ist die Reduzierung des Busfaktors ein Engpass im Unternehmenswissen, bei dem die Anzahl der Wissensinhaber zur Einheit tendiert. Sie müssen dieses Wissen vom Leiter des Entwicklers, von Whiteboards, Tickets und Gesprächen in der Küche, in einen einzigen Raum übertragen, damit jeder mit ihnen arbeiten und Beiträge leisten kann.
Zweitens, um den Einstieg von Neulingen in Projekte zu vereinfachen, was besonders für verteilte Teams und Teams mit einer bestimmten Anzahl ausgelagerter Entwickler sowie für Unternehmen mit einem ganz bestimmten Geschäftsbereich wichtig ist, ist die Chance, einen vorgefertigten Spezialisten zu finden, gleich Null.
Drittens für die Bildung einer soliden Unternehmenskultur Transparenz "nicht in Worten". Ein Entwickler in einem solchen Umfeld versteht klar die Punkte des beruflichen Wachstums, welche anderen Technologien er im Unternehmen ausprobieren kann, was er lernen muss.
Was tun?
Die Dokumentation innerhalb der Wissensdatenbank des Unternehmens kann von jedem Mitglied des Teams verfasst werden. Diese Möglichkeit muss für sie vereinfacht werden, damit sie sich als Eigentümer des betreffenden Ergebnisses fühlen.
Sie benötigen jedoch auf jeden Fall eine Person, die die Funktionen eines Informationsarchitekten übernimmt - einheitliche Regeln, Struktur, Logik, Stil festlegen und Dokumente korrekt in Räumen platzieren.
Öffnen Sie die Möglichkeit, Dokumente zu bearbeiten und für Teammitglieder zu erstellen, nachdem Sie zuvor die Spielregeln vereinbart haben. Automatisieren Sie diese Regeln maximal - verlassen Sie sich nicht auf das Team, erstellen Sie Vorlagen, markieren Sie Inhalte automatisch mit Tags, konfigurieren Sie das Hochladen aus dem Repository in die Wissensdatenbank (ich möchte übrigens einen separaten Artikel dazu verfassen).
Es ist wichtig, dass Entwickler sehen, dass Dokumente im Unternehmens-Wiki nicht sterben.
Ein wichtiges Prinzip: Definition eines internen Dokuments. Dies ist der Moment, in dem Änderungen oder Kommentare vorgenommen wurden , dh der Moment der Zusammenarbeit. Das ist sein Wert, sie wollen Zeit damit verbringen. Nicht ergänzen - dies bedeutet, dass der Lieferprozess, die Implementierung der Suche schlecht organisiert oder das Tool unpraktisch ist.
Das potenzielle Problem dieses Ansatzes ist die Ansammlung von Änderungen und Kommentaren als Schneeball. Es ist schwierig, den Überblick zu behalten. Oft werden doppelte Dokumente erstellt.
Um dies zu verhindern, können und sollten Sie: A. Setzen Sie das Team auf einen Vektor, legen Sie Regeln fest und erschweren Sie den Vorgang, diese nicht zu befolgen (z. B. haben wir die Schaltfläche Erstellen in Confluence ausgeblendet und die Vorlagenauswahl obligatorisch gemacht). B. Um die Rechte mit Bedacht abzugrenzen und die Bearbeitungsprozesse bequem für diejenigen zu konfigurieren, die für die Informationsarchitektur verantwortlich sind.
Und dann wird die perfekte Welt kommen
Entwickler werden nicht aufhören, sich gegenseitig Fragen zu stellen, auch dumme und sich wiederholende . Sie werden nicht lernen, alle Antworten in der Wissensbasis selbst zu finden. Wir haben internen Humor, wenn Entwickler aufgrund der Einschränkungen des Confluence-Suchindex nichts finden können, fragen sie mich als Informationsarchitekten. Wir nennen es Sveta-basierte Suche.
Trotz dieser Einschränkungen werden die Struktur der Wissensbasis, die einheitliche Benennung von Seiten und die Verwendung von Beschriftungen dazu angeregt, Wissen zu suchen und zu erstellen, sodass sie beispielsweise nicht ständig wiederholte Fragen beantworten.
Ein weiterer Life-Hack, den wir angewendet haben, besteht darin, immer einen Geschäftskontext in Dokumente aufzunehmen, auch wenn es sich um eine Beschreibung einer Bibliothek oder Klasse oder eine Checkliste für eine Aufgabe handelt. Es ist wichtig zu verstehen, was dies für den Kunden bedeutet.
Nun zum Üben
Im nächsten Teil geht es um das „Wie“, mit welchen internen Funktionen von Confluence (ja, wir verwenden den Atlassian-Stack) diese Prinzipien implementiert werden können.
Muster
Wir haben vorgefertigte Vorlagen für verschiedene Arten von Dokumenten erstellt, die wir am häufigsten schreiben - technische Spezifikationen, Anleitungen, Checkliste. Sie können im Admin-Bereich konfiguriert werden. Vorlagen werden benötigt, damit der Entwickler beim Erstellen eines Dokuments keine leere Seite vor sich sieht und bereits Anweisungen dazu hat, was in diesem oder jenem Abschnitt zu schreiben ist. Wenn Sie möchten, dass Dokumente eines bestimmten Typs in einen Abschnitt fallen und Metainformationen darauf angezeigt werden (dies ist beispielsweise praktisch, um die Komponenten eines komplexen Produkts oder einer Reihe von Mikrodiensten nach einem Schema zu beschreiben), erstellen Sie eine Blaupause. Dies ist wie eine Vorlage mit maximaler Geschwindigkeit.
In ihnen richten wir das Seitenlayout und die Überschriften ein, wobei nur ein paar Wörter, eine Überschrift mit einem Status, Bilder, Tabellen, Codeblöcke und sogar Variablen ersetzt werden müssen.
Variablen sind vorkonfigurierte Inhaltselemente, denen ein weiterer Dokumenteditor Bedeutung beimessen sollte, z. B. Text eingeben oder aus einer Liste auswählen.
Sie können der Vorlage auch im Voraus Tags hinzufügen. Wenn es sich um einen engen Dokumenttyp handelt, können Sie Benutzer als Prüfer angeben, z. B. wenn ein eindeutiger Workflow nach Namen und Jira-Makro vorhanden ist, und ein Ticket von Jira anhängen. Unsere Erfahrung zeigt, dass bis zu 80 Prozent der Aufgaben mit Vorlagen abgedeckt werden können.
Seitenlayout
Ein weiteres wichtiges Element ist die Erstellung einer verständlichen und schönen Landingpage im Teambereich. Dazu verwenden wir das Seitenlayout und die Makros Bedienfeld, Spalte und Abschnitt.
Unten finden Sie ein Beispiel für einen Bereich unseres Entwicklungsteams.
Verwenden Sie benutzerfreundliche Seitennamen. Wie Sie vielleicht wissen, unterstützt Confluence keine identischen Seitennamen innerhalb desselben Bereichs. Behalten Sie klare Seitennamen bei, z
Schlechter Name Python
Guter Name Python Styleguide für das interne Serviceteam
Etiketten
Confluence weist einige Einschränkungen hinsichtlich des Suchalgorithmus im Zusammenhang mit der Inhaltsindizierung auf. Und für die Wissensbasis des Unternehmens sind genau das Finden und die Verbundenheit die dringendsten Themen. Wir haben einen ganzen Artikel in der Wissensdatenbank mit dem Titel Wie man die Confluence-Suche schlägt. Wenn Sie möchten, werde ich ihn in den Kommentaren veröffentlichen.
Um diese Einschränkungen zu überwinden, verwenden wir ein Etikettensystem. Tatsächlich handelt es sich hierbei um Tags, die das Thema des Inhalts kennzeichnen, und warum Sie damit den Inhalt eines bestimmten Themas an einer Stelle in Form einer Art RSS-Feed (Makroinhalt nach Bezeichnung) zusammenfassen können. Wir haben also Themenindizes konfiguriert.
Wenn Sie bereits Hunderte von Seiten in der Datenbank haben, empfehle ich Ihnen, mit den folgenden Übungen zu beginnen:
- Eine Liste aller Labels finden Sie unter der folgenden URL https: // <my-host-name> /labels/listlabels-alphaview.action.
- Suchen Sie alle Inhalte, die nicht mit Beschriftungen versehen sind, in der erweiterten Suchzeichenfolge: type: page NOT labelText: [a TO z] NOT labelText: [0 TO 9].
Was können Sie jetzt tun?
- Geben Sie Entwicklern das Recht zum Bearbeiten, aber mit Bedacht.
- Denken Sie über die Struktur des Befehlsbereichs nach und erstellen Sie eine bequeme Zielseite.
- Passen Sie die Vorlagen an.
- Verwenden Sie Etiketten.
- Bearbeiten Sie das Dokument eines anderen oder schreiben Sie einen Kommentar, damit dieses Dokument funktioniert.