Diese Seite enthält die Details zu einem Projekt für technisches Schreiben, das für die Google-Produktsaison von Google Docs akzeptiert wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- WordPress
- Technischer Redakteur:
- tacitonisch
- Projektname:
- Vollständiger und überarbeiteter Style Guide für die Dokumentation
- Projektdauer:
- Langfristig (5 Monate)
Projektbeschreibung
Synopse:
WordPress ist eine globale gemeinnützige Softwareorganisation, die sich der globalen Community mit Software widmet, bei der die Barrierefreiheit, Leistung, Sicherheit und Nutzerfreundlichkeit im Vordergrund stehen. Das Anliegen von WordPress strebt die Demokratisierung von Veröffentlichungs- und Open-Source-Software im Web an. Im digitalen Zeitalter ist eine Website im wahrsten Sinne des Wortes die Online-Fassade einer Organisation/Einzelperson. WordPress dient einer immensen Aufgabe, mit der Software Hunderte Millionen Nutzer effizient zu bedienen – was auf die 35% des Internets zurückzuführen ist, auf die es läuft. Um diese Nutzer noch effizienter bedienen zu können, erweist sich die Dokumentation als unerlässlich und wird von den meisten Entwicklern, Administratoren und Endnutzern verwendet. Daher kann die Dokumentation als Hauptfaktor des WordPress-Ökosystems geschaffen werden. Die aktuelle WordPress-Dokumentation enthält keine universellen und einheitlichen Regeln und Stilrichtlinien für die Veröffentlichung. Ziel dieses Vorschlags ist es, vollständige und überarbeitete Richtlinien zum Dokumentationsstil zu erstellen, die allgemein für die WordPress-Dokumentation anwendbar sind. Die Projektidee beinhaltet die Konsolidierung aller Aspekte der Design- und Stilrichtlinien wie Semantik, Syntax, Grammatikrichtlinien, Zeichensetzung, entwicklungsspezifische Regeln, Designattribute und Formatierungsmerkmale. Es berücksichtigt auch Sprachkonventionen wie Sprache, Tonfall, Zeitform, alle Wortarten sowie Namenskonventionen. Die verwendeten Tools, Sprachen und Plattformen sind WordPress CMS, GitHub, Markdown und können auch aus PHP/MySQL, HTML/CSS und JavaScript bestehen.
Projektplan:
Aktueller Stand der Styleguides für die WordPress-Dokumentation: Das Dokumentationsteam von WordPress hat eine unbekannte, aber einstimmige Methode für die Veröffentlichung von Richtlinien implementiert. Hin und wieder werden jedoch einige Elemente vorausgesetzt und der Prozess wird spekulativ. Es gibt keinen festen Standard und kein Kriterium für das Schreiben und Veröffentlichen von Artikeln für WordPress. Das Dokumentationsteam hat projektspezifische Stilrichtlinien geschrieben, aber keine, die universell anwendbar sind. Die meisten Stilrichtlinien, die es gibt, sind nicht in einem Handbuch zusammengefasst oder wurden eingestellt und müssen aktualisiert werden. Daher ist es erforderlich, einen einheitlichen Styleguide zur Standardisierung der WordPress-Dokumentation zu entwerfen und zu entwickeln.
Lernziele:
Über 35% der Websites im Internet laufen auf WordPress, was wiederum darauf hinweist, dass Millionen von Entwicklern und Endnutzern die beeindruckenden Funktionen von WordPress nutzen. Die entsprechende Dokumentation ist ein wichtiges Element, damit diese Entwickler und Nutzer diese Funktionen problemlos und effizient ausführen können, selbst im Falle von Unannehmlichkeiten. Das übergeordnete Ziel dieses Projektvorschlags ist die Standardisierung eines Design- und Styleguides, die Vereinheitlichung vorhandener Styleguides und die Aktualisierung sowie das Anhängen neuer Vorschriften und Spezifikationen für die WordPress-Dokumentation. Dies würde eine Nutzerfreundlichkeit, Einfachheit und Einheitlichkeit in der WordPress-Dokumentation ermöglichen.
Umsetzung:
Wie vom Mentor (Jon Ang) für dieses Projekt vorgeschlagen, kann das Projekt in vier Phasen angegangen werden: Erkennung, Definition, Implementierung und Verwaltung. Vor Beginn des Projekts werde ich während des Vorpraktikums mit meiner beratenden Person zusammenarbeiten und einen geeigneten Zeitplan und einen Zeitplan ausarbeiten, der meinem anschließenden Zeitplan und den Liefergegenständen entspricht. Ich werde mich weiter mit dem WordPress-System und den Arbeitsprotokollen für dieses Projekt vertraut machen.
Zu Beginn des Praktikums werde ich die Zusammenfassung des Plans mit meiner beratenden Person besprechen und entwerfen. Die Anforderungen und Notwendigkeiten werden bestimmt. Zunächst werde ich den Ablauf der Dokumentation und den Prozess der Nutzerinteraktion skizzieren. Anschließend werden die Layout-Wireframes für jeden Abschnitt, jede Kategorie und jede Komponente skizziert. Diese Layouts werden dann von meinem Mentor überprüft. Bei Bedarf werden die Layouts neu gestaltet und einige Komponenten werden hinzugefügt oder entfernt. Anschließend werde ich Nutzungsstudien durchführen, um die Usability und Machbarkeit des Ablaufs der Benutzeroberfläche zu ermitteln. Anschließend wird der Dokumentations-Styleguide pro Abschnitt implementiert (wie im Diagramm unten dargestellt). Die Styleguides von anderen Organisationen, die unter einer Open-Source- oder Creative-Commons-Lizenz stehen, können als Anhang hinzugefügt werden. Sollten während dieser Phase Probleme mit der Nutzungsfreundlichkeit auftreten, werde ich sie neu gestalten.
Tests und Optimierungen werden durchgeführt, nachdem der Styleguide fertiggestellt und in HelpHub integriert wurde. Alle Sicherheitslücken, redundanten Elemente oder Komponenten werden behoben. UI- und Codetests werden durchgeführt und unerwünschte Fehler und Fehler werden bei Bedarf behoben. Für den gesamten Styleguide wird eine letzte Qualitätskontrolle bezüglich Sprache, Grammatik, Rechtschreibung, Zeichensetzung usw. durchgeführt.
Aufgaben, die aufgrund unvorhergesehener Verzögerungen ausstehen, werden im Pufferzeitraum abgeschlossen. Zusätzliche Funktionen oder Merkmale, die im Laufe des Projekts als durchführbar eingestuft werden, können nach Abschluss der letzten Tests implementiert werden. Ein Bereitstellungsplan wird erstellt und das fertige Produkt wird eingereicht.
Tools und Methoden:
Die Dokumentation wird auf einer Plattform für die Zusammenarbeit, z. B. Google Docs, zusammengestellt und bearbeitet. Falls die Veröffentlichung über GitHub erforderlich ist, können auch Auszeichnungssprachen wie Markdown oder GitHub Flavored Markdown implementiert werden. Für Design- und Stilstandards kann auch auf Open-Source-Stilrichtlinien verwiesen werden. Schließlich wird das fertige Dokument mithilfe von WordPress formatiert und veröffentlicht.
Komponententabelle:
Dies ist eine vollständige Liste der Komponenten, die im Styleguide implementiert werden können. Dokumentrichtlinien - Barrierefreiheit, Dokumentstruktur, Codierung, externe Quellen, Fakten, Schriftarten, globale Zielgruppe, Inklusivität, Rechtmäßigkeit, Barrierefreiheit auf mehreren Plattformen, Nicht mehrdeutig, Keine übermäßigen Behauptungen, Seitenlayout, politische Richtigkeit, Protokolle, Sicherheit, Satzstruktur, prägnante Formulierung, Tonalität und Stil, Unvoreingenommen
Sprache und Grammatik – Abkürzungen und Akronyme, Affirmation und Negation, Artikel, Großschreibung, Klausel, direkte/indirekte Sprache, erste/zweite/dritte Person, Geschlechter, Glossar, Substantive, Präfixe und Suffixe, Präpositionen, Pronomen, Verweise, Slang und Jargon, Rechtschreibung, Fachbegriffe, Verben
Zeichensetzung - Apostroph und Anführungszeichen, Doppelpunkte und Semikolons, Kommas, Ellipsen, Ausrufezeichen, Binde- und Bindestriche, Klammern, Punkte, Fragezeichen, Schrägstriche
Formatierung, Zusammenfassungen, Einführung, Vorworte, Markennamen, Produktnamen, Bildunterschriften, Code-Snippets, Codeblöcke, Datum und Uhrzeit, Zeitzonen, Orte, Währungen, Dateinamen, Fußnoten, Überschriften und Titel, Hervorhebung (fett, kursiv, Unterstrichen, Abstände, Links und URLs), Einrückung, Aufzählung, Index, Links und URLs, Indentation, Index, Links und URLs, Einzüge
Benutzeroberfläche - Aktivitäten, Schaltflächen, Code-Snippets, Codeblöcke, Befehlszeile, Dialogfelder, Menüs und Drop-down-Menüs, Pop-ups und Warnungen, Tabs, Terminologie, UI-Elemente, Fenster
Code – CSS, HTML, JS, Markdown, MySQL, PHP, Syntax, XML
Wortwörterbuch/-Glossar - A bis Z