For the past couple of weeks we have been actively creating content for the Creative Commons WordPress Base Theme Usage Guide. Currently the draft content is under final review before it is migrated to the main docs site.
Our Strategy
Our main goal in creating the docs is to create rich, intuitive, engaging, and beautifully presented community facing documentation for the Creative Commons WordPress Base Theme.
In alignment with the defined goal, our core focus is to create the docs collaboratively.
The CC WordPress team consists of I, Jacqueline Binya, Hugo Solar and Timid Robot Zehta. Although our team is small it is quite diverse. It consists of a diverse mix of technical skills: I am a junior developer whereas Hugo and Timid are way senior. We also have non-native and native English speakers.
Diversity is important as we hope to create a high quality product that caters for everyone.
My role as the tech writer/frontend developer is to create the content: write the documentation, build the docs site and also to create all illustrative media.
During the content creation phase, the first step involved creating the skeleton of the actual docs site. We created a git branch called docs within the creative-commons/wp-base-theme repository. All content related to the documentation is persisted in that branch. So,please feel free to contribute. We then used JamDocs, a Gridsome theme to quickly scaffold the site. We had to adapt the theme so as to make it meet our own specific needs, this involved overhauling the styles and changing the functionality of some of the features in the theme. After that was completed, we then created a Google Doc we use for collaboratively writing the draft content for the docs site.
Tech Stack
As it was mentioned we used Gridsome a static generator for Vuejs. We chose Gridsome because:
We wanted to lower the barrier of entry to contributing:
- Gridsome/Vuejs community is very active, help is but a click away.
- The Gridsome official documentation is very resourceful and well maintained.
Gridsome is highly flexible: The content for the actual documentation is written in Markdown but using @gridsome/vue-remark, which is a Gridsome plugin, we are able to use javascript in Markdown. We intend to include a copy to the clipboard Vuejs component in the site.
Time Constraint: This project is a short running project which has to be completed in a 3 month period. Through the use of JamDocs, a Gridsome templating theme as well various plugins it was easy and fast to get started we were able to add more functionality to the theme with minimal effort.
Ease of integrating CC Vocabulary with Gridsome: it is a requirement that the general aesthetics of all front facing Creative Commons applications is derived from the CC Vocabulary Design System. Major cons for using a design system include the ensuring uniformity in design for all front facing CC products.
Tools Used
Figma was used to make assets(banners, logos and illustrations) in the theme. The illustrative media was created with accessibility in mind and all the topography used in the illustrative assets was derived from the CC Vocabulary.
VokoScreenNG: an open source screencast recording tool used to record all the screen cast demos available in the docs site.
ShortCut: an open source video editing tool.
What comes next ?
After the final review is completed and all feedback implemented we will migrate all the content to the main docs site.
Stay tuned for an update about the launch of the CC WP Base Theme Docs site.