Google Season of Docs

Ideas page for the Season of Docs project

Introduction

In 2019 for the first time, Google is trying out a new programme called Seasons of Docs. From their website:

The goal of Season of Docs is to provide a framework for technical writers and open source projects to work together towards the common goal of improving an open source project's documentation. For technical writers who are new to open source, the program provides an opportunity to gain experience in contributing to open source projects. For technical writers who're already working in open source, the program provides a potentially new way of working together. Season of Docs also gives open source projects an opportunity to engage more of the technical writing community.

As Plone is a large project, with documenation that has slowly and sometimes organically developed over the course of the years, we welcome this opportunity to connect with tech writers and improve our documentation. 

 

Project Ideas

 

Project 1: Improve The Developer Onboarding Experience For Plone 6

Plone is a full-featured Content Management System, and as such the documentation caters to a range of audiences, including

  • end users, who create content for a website
  • site administrators, who can use an extensive control panel to set up languages, workflows, security requirements and many other features
  • theme writers, who can implement a specific design
  • add-on developers, who extend Plone's functionality by creating custom add-ons
  • core developers, who work to enhance Plone itself

Now, while there is a wealth of information available on docs.plone.org and training.plone.org the information in there is not always easy to find. Plone has over 17 years of history, and technologies have come and gone. Over those years, there have also been several iterations of what was considered "best practice" at the time. Remnants of this remain in the documentation.

This project would focus on the (as yet unreleased) Plone 6. For that release, there are a number of older technologies that will no longer be supported, making the picture simpler.

We would like to create, together with a tech writer, a better onboarding experience for starting developers. As an end user, using Plone is straightforward and documented. When you want to start developing add-ons, the learning curve can be steep as there are many concepts to grasp and it can be hard to know what the current best practices are.

This would include:

  • quickstart guides for both setting up a local instance of Plone, and for developing add-ons for Plone.
  • a strict focus on current technology, leaving out any confusing references to older technologies
  • include best practices on how to set up a development environment with the recommended setup for your editor
  • use (and explicitly describe) the best-practice style guide for writing code, tests, and documentation for add-ons.
  • how to write and run tests according to the latest methods
  • how and where to release your add-on so that other Plone community members can find it and start cooperating

While most of the current documentation is written in ReStructuredText, we are also very open to writing new documentation in Markdown, more specifically the CommonMark dialect

Skills required: it would help if a tech writer is familiar with the concept of a Web CMS, some knowledge of Python is a plus but not required. Your most important skill would be to keep the focus on the goal of onboarding, and keeping consistency in tone and difficulty level within the project. 

 

 

Project 2:  Improve Documentation For The React-based Frontend "Volto"

The Plone community is developing a new, React-based frontend called Volto. Developing websites with Volto is done purely in React, using SemanticUI components to create modern, interactive websites. The 'glue' between this and all the advanced functionality of Plone is provided by plone.restapi, a package that provides the features of Plone over an API. In this way, website developers can use the rich set of features that Plone provides while essentially treating it as a 'black box'. 

The audience for this project would be: web developers who are already familiar with React, or who want to develop with React to create websites, but want to use a stable, mature and feature-rich backend to provide Content Management functionality without having to learn Plone and/or Python.

The project would include:

  • improving the Volto documentation
  • going over the documentation of plone.restapi, separating out a purely "consumer" perspective: what are the REST endpoints that I can use to create my website, and what benefits do each of them bring? The current documentation for this package is quite extensive on the exact specification of the endpoints, but needs more narrative description on "Why would I want to use this? What problems does it solve?".

The current documentation is written in Markdown, and should stick to the CommonMark dialect

Skills required: some familiarity with React is a plus, and a generic knowledge of web technologies like REST calls and API's. Explicit knowledge of Plone is in no way required, as the audience for this project should be able to use the Plone backend as a black box.