This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- Creative Commons
- Technical writer:
- JackieBinya
- Project name:
- WordPress base theme usage guide
- Project length:
- Standard length (3 months)
Project description
During the technical writer application phase of the GSOD-2020, I had several interactions with Hugo Solar, who is the mentor of the Creative Commons WordPress base theme documentation project.
In my initial contact with him, I sought help in understanding the objectives of creating the WordPress base theme usage guide, he was very helpful and quickly got me on board with the project. All the consecutive interactions we had after that were about refining the objectives of the CC WordPress Base theme documentation.
When I reached a stage I felt I understood the project's requirements and objectives I then went on to create a draft proposal for the CC WordPress Base Theme Usage Guide.
The proposal was created using the Creative Commons official template for intern applications. It provides information about the project synopsis, proposed project structure, and layout of the new WordPress Base Theme documentation as well as information about timelines and deliverables for the document creation phase.
Hugo Solar then reviewed my draft proposal and gave me feedback to make improvements. Throughout this process, he was always available to answer questions about the project.
I implemented the feedback given and my final proposal for Building D&I Badging documentation is available in the link below as a Google Doc
https://docs.google.com/document/d/1XmIsMTLstbhRRSaNFP538YOXJiS0G5QrN6EzuqJfRy4/edit?usp=sharing
Alternately, a brief summary of my proposal, and is found below:
Creative Commons - WordPress base theme usage guide A proposal prepared by Jacqueline Binya, 28 June 2020
Project Synopsis The ultimate goal of this project is to create rich, intuitive, engaging, and beautifully presented community facing documentation for the Creative Commons WordPress Base Theme.
Project Plan The Problem Currently, the Creative Commons WordPress Base theme has no documentation, this acts as a barrier for effective utilization of the theme within the community. My goal is to create a complete usage guide for the theme and also implement abstractions in the current codebase of the WP Base theme so as to make it easier to use the theme.
The Solution Create futuristic docs using modern frameworks like Gatsby. Gatsby has starters that we can use to bootstrap the new WordPress Base Theme documentation. An example starter is the gatsby-gitbook-starter which comes out of the box powered with support for search engine optimization (SEO), markdown, and Algolia ( a tool used to integrate for search in static sites). In addition to that any Gatsby generated site can easily be optimized to integrate internationalization and accessibility. In creating the documentation my intentions are to make it as intuitive as possible by: - writing the docs in an easy to understand manner and taking care to avoid ambiguity and the use of excessive complex technical jargon. - by incorporating graphical illustrations and media in the documentation for use as visual aids for learning. - using examples that demonstrate how to execute common tasks e.g customizations.
The abstractions I hope to implement will include ensuring that most of the core functionality of the WP Base Theme like hooks for instance can be leveraged on by users from the WordPress Admin Panel. In addition to that, I would love to create a starter child theme for the WP Base Theme in a separate repository. Having a starter child theme would provide a smoother and faster onboarding experience for new users. Once the documentation is complete and approved it will then be published and hosted online.
The proposed structure of the CC WordPress Base Theme Usage Guide - The proposed documentation will be divided into different sections listed below. The sub-list items under each proposed section then give more detail about the actual content that will be found in the respective sections.
Overview Section - Outline the definition, intentions, and features of the Creative Commons(CC) WordPress Base Theme. * Definition: Briefly describe the CC WP Base Theme. * Intentions: Outline the aims/ intentions of the CC WP Base Theme * Features: Outline the features of the CC WP Base Theme
Getting Started Section - Requirements * Outline the requirements for installing the CC WordPress Base Theme i.e. - WordPress version - PHP version - Composer etc. - Installation Guide * Outline how users can use zip to install CC WordPress Theme * Outline how users can get started by cloning the WP base theme from GitHub. * Outline how users can install dependencies in the project. * Explain how users can configure dependency Queulat. * Explain how users can activate the theme in their local WordPress development environment.
Usage Guide - Overview * Explain the term child theme * State the advantages of using a child theme. * Inform users that the recommended way to edit the WP Base theme is through a Child Theme. * Highlight the fact that the WP Base Theme has to be installed and activated before users can make a child theme.
Using a Child Theme - Explain how users can create a child theme of the WP Base Theme using a starter. Use a video to explain how users can create a child theme from the starter.
Customization In the sub-sections listed below, we outline how users can use the WordPress Customizer and the WordPress Admin Panel to make customizations. We will also incorporate the use of graphical illustrations to make our descriptions more intuitive. - Customize site description or tag line. - Custom Navigation Menus - Customize CSS - Adding Pages - Adding Posts - Widgets - Add and remove widgets from the WordPress Admin Panel - Add widgets using Customizer with live preview
Advanced Customizations Section - Customizing CSS Section * Describe the components that constitute the styling of the theme: - CC Vocabulary - Bulma - Sass * Explain how Sass is set up in the project. The explanation should include information about: (i)The location of the sass files in the project structure (ii)The npm scripts which can be used to build and watch sass * Explain how users can then customize the sass styles in the child theme i.e through the installation of specific npm dependencies * Explain how the component class (class-component.php) is used to customize the styles of specific components
- Hooks Section
Overview
- Explain the term hooks
- Explain why users would need to leverage on hooks.
- Outline the types of hooks available.
Using Actions
- List the actions available in the WP Base theme and its positioning
- Explain how these actions can be implemented.
*Using Filters - List the filters available in the theme and explain how they can be implemented
Updating the theme Section - Explain how users can update the theme.
Licensing Section * Explain the licensing of the project and what it means to people who may want to use the CC WP Base Theme in their personal projects.
Contributing Section * Add a well detailed contributing guide * Outline the Code of Conduct * Community: provide information about the Creative Commons community channels and how contributors may participate etc.