Auf dieser Seite finden Sie die Details zu einem Projekt für technisches Schreiben, das für Google Season of Docs angenommen wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- WordPress
- Technischer Redakteur:
- tacitonic
- Projektname:
- Vollständiger und überarbeiteter Styleguide für die Dokumentation
- Projektlänge:
- Lang andauernd (5 Monate)
Projektbeschreibung
Zusammenfassung:
WordPress ist eine globale Nonprofit-Softwareorganisation, die sich der Bereitstellung von Software für die globale Community verschrieben hat, die sich durch Barrierefreiheit, Leistung, Sicherheit und Nutzerfreundlichkeit auszeichnet. WordPress möchte das Veröffentlichen und Open-Source-Software im Web demokratisieren. In unserem digitalen Zeitalter ist eine Website buchstäblich die Onlinefassade einer Organisation oder eines Einzelpersonen. WordPress hat die immense Aufgabe, mit seiner Software Hunderte von Millionen Nutzern effizient zu dienen – was auf die 35% des Internets zurückzuführen ist, die es betreibt. Um diese Nutzer noch effizienter zu unterstützen, ist eine Dokumentation unerlässlich. Sie wird von den meisten Entwicklern, Administratoren und Endnutzern verwendet. Die Dokumentation kann daher ein wesentlicher Faktor im WordPress-Ökosystem sein. Die aktuelle WordPress-Dokumentation enthält keine universellen und einheitlichen Regeln und Stilrichtlinien für die Veröffentlichung. Ziel dieses Vorschlags ist es, eine vollständige und aktualisierte Reihe von Stilrichtlinien für die WordPress-Dokumentation zu erstellen, die universell für die WordPress-Dokumentation anwendbar sind. Die Projektidee umfasst die Konsolidierung aller Aspekte von Design- und Stilrichtlinien wie Semantik, Syntax, Grammatik, Zeichensetzung, entwicklungsspezifische Regeln, Designattribute und Formatierungsmerkmale. Außerdem werden Sprachkonventionen wie Modus, Ton, Zeitform, alle Wortarten sowie Namenskonventionen berücksichtigt. Die verwendeten Tools, Sprachen und Plattformen sind WordPress CMS, GitHub, Markdown und können auch PHP/MySQL, HTML/CSS und JavaScript umfassen.
Projektplan:
Aktueller Stand der Styleguides für die WordPress-Dokumentation: Das WordPress-Dokumentationsteam hat für die Veröffentlichungsrichtlinien eine nicht deklarierte, aber einstimme Methode implementiert. Hin und wieder werden jedoch einige Elemente vorausgesetzt und der Prozess wird spekulativ. Es gibt keinen festen Standard und kein festes Kriterium für das Schreiben und Veröffentlichen von Artikeln für WordPress. Das Dokumentationsteam hat projektspezifische Stilrichtlinien verfasst, aber keine, die allgemeingültig sind. Die meisten vorhandenen Stilrichtlinien sind nicht in einem Handbuch zusammengefasst oder veraltet und müssen aktualisiert werden. Daher muss ein einheitlicher Styleguide entworfen und entwickelt werden, um die WordPress-Dokumentation zu standardisieren.
Lernziele:
Über 35% der Websites im Internet werden mit WordPress betrieben. Das bedeutet, dass Millionen von Entwicklern und Endnutzern die beeindruckenden Funktionen von WordPress nutzen. Dokumentation ist ein wichtiges Element, um diese Entwickler und Nutzer dabei zu unterstützen, diese Funktionen effizient und problemlos auszuführen – auch im Falle von Unannehmlichkeiten. Das Hauptziel dieses Projektvorschlags besteht darin, einen Design- und Styleguide zu standardisieren, vorhandene Styleguides zu vereinheitlichen und zu aktualisieren sowie neue Vorschriften und Spezifikationen für die WordPress-Dokumentation hinzuzufügen. Dies würde für Nutzerfreundlichkeit, Einfachheit und Einheitlichkeit in der WordPress-Dokumentation sorgen.
Umsetzung:
Wie der Mentor (Jon Ang) für dieses Projekt vorgeschlagen hat, kann das Projekt in vier Phasen unterteilt werden: Entdeckung, Definition, Implementierung und Wartung. Vor Beginn des Projekts, während der Zeit vor dem Praktikum, werde ich mit meinem Mentor zusammenarbeiten und einen geeigneten Zeitplan und Zeitplan erstellen, der meinen nachfolgenden Zeitplan und meine zu erbringenden Leistungen widerspiegelt. Ich werde mich mit dem WordPress-System und den Arbeitsprotokollen für dieses Projekt vertraut machen.
Zu Beginn des Praktikums werde ich mit meinem Mentor die Zusammenfassung des Plans besprechen und entwerfen. Die Anforderungen und Anforderungen werden festgelegt. Zuerst skizziere ich den Ablauf der Dokumentation und den Prozess der Nutzerinteraktion. Anschließend werden die Layout-Wireframes der einzelnen Abschnitte, Kategorien und Komponenten skizziert. Diese Layouts werden dann von meinem Mentor überprüft. Bei Bedarf werden die Layouts neu gestaltet und einige Komponenten hinzugefügt oder entfernt. Anschließend führe ich Nutzungsstudien durch, um die Nutzerfreundlichkeit und Machbarkeit des Interface-Flows zu bestimmen. Anschließend wird der Dokumentations-Styleguide (wie in der folgenden Abbildung dargestellt) pro Abschnitt implementiert. Auch Styleguides anderer Organisationen, die unter Open-Source- oder Creative-Commons-Lizenzen stehen, können in unseren Leitfaden aufgenommen werden. Sollten in dieser Zeit Probleme mit der Nutzerfreundlichkeit auftreten, werde ich sie neu gestalten.
Tests und Optimierungen werden durchgeführt, nachdem der Styleguide fertiggestellt und in HelpHub eingebunden wurde. Sicherheitslücken, redundante Elemente oder Komponenten werden behoben. UI- und Codetests werden durchgeführt und bei Bedarf werden unerwünschte Fehler und Fehler behoben. Es erfolgt eine abschließende Qualitätskontrolle des gesamten Stilhandbuchs hinsichtlich Sprache, Grammatik, Rechtschreibung, Zeichensetzung usw.
Aufgaben, die aufgrund unvorhergesehener Verzögerungen ausstehend sind, werden im Pufferzeitraum abgeschlossen. Zusätzliche Funktionen, die im Laufe des Projekts als machbar eingestuft werden, können nach Abschluss der abschließenden 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 wie Google Docs zusammengestellt und bearbeitet. Wenn die Veröffentlichung über GitHub erforderlich ist, können auch Markup-Sprachen wie Markdown oder GitHub Flavored Markdown implementiert werden. Für Design- und Stilstandards können auch Open-Source-Stilrichtlinien referenziert werden. Schließlich wird das fertige Dokument mit WordPress formatiert und veröffentlicht.
Komponententabelle:
Dies ist eine vollständige Liste der Komponenten, die im Styleguide implementiert werden können. Richtlinien für Dokumente – Barrierefreiheit, Dokumentstruktur, Codierung, externe Quellen, Fakten, Schriftarten, globales Publikum, Inklusivität, Legalität, plattformübergreifende Barrierefreiheit, nicht eindeutig, keine übermäßigen Behauptungen, Seitenlayout, politische Richtigkeit, Protokolle, Sicherheit, Satzstruktur, prägnanter Text, Ton und Stil, unverzerrt
Sprache und Grammatik – Abkürzungen und Akronyme, Bejahung und Verneinung, Artikel, Großschreibung, Nebensatz, Direkte/indirekte Rede, Erste/Zweite/Dritte Person, Geschlechter, Glossar, Substantive, Präfixe und Suffixe, Präpositionen, Pronomen, Verweise, Slang und Fachjargon, Rechtschreibung, Fachbegriffe, Zeitformen, Verben, Aktiv/Passiv
Satzzeichen: Apostrophe und Anführungszeichen, Doppelpunkte und Semikolons, Kommas, Auslassungspunkte, Ausrufezeichen, Bindestriche und Gedankenstriche, Klammern, Punkte, Fragezeichen, Schrägstriche
Formatierung – Zusammenfassungen, Einführungen, Vorworte, Markennamen, Produktnamen, Bildunterschriften, Code-Snippets, Codeblöcke, Datum und Uhrzeit, Zeitzonen, Orte, Währungen, Dateinamen, Fußnoten, Überschriften und Titel, Hervorhebungen (Fettdruck, Kursivschrift, Unterstreichung, Durchstreichen, Anführungszeichen), Einzüge, Index, Links und URLs, Listen, Aufzählungspunkte, Nummerierung, Medien (Bilder, Videos) und Illustrationen, Notizen, Warnungen, Tipps, Zahlen und Telefonnummern, Polyglotte, Übersetzung, Schriftsysteme, Abstände, Tabellen, Text, Marken, Urheberrechte, Patente, Zitate, Anleitungen und Verfahren, UI-Elemente, Maßeinheiten
Benutzeroberfläche – Aktivitäten, Schaltflächen, Code-Snippets, Codeblöcke, Befehlszeilenschnittstelle, Dialogfelder, Menüs und Drop-down-Menüs, Pop-ups und Benachrichtigungen, Tabs, Terminologie, UI-Elemente, Fenster
Code – CSS, HTML, JS, Markdown, MySQL, PHP, Syntax, XML
Wörterbuch/Glossar zur Wortverwendung - A bis Z