SeasonOfDocs

Yocto Project Season of Docs

About

The Yocto Project is an open-source project that delivers a set of tools that create operating system images for embedded Linux systems. The Yocto Project tools are based on the OpenEmbedded (OE) project, which uses the BitBake build tool, to construct complete Linux images. BitBake and OE are combined to form a reference build host known as Poky which includes the following core components. This video will help explain what it's all about.

Richard Purdie, the Yocto Project's lead developer and Linux Foundation Fellow, considers documentation to be one of the cornerstones of this project. The quality and breadth of the documentation is one of the aspects of the project which is appreciated by and commented upon by our users. One of the very first members of that team to work on what became the Yocto Project 10 years ago was Scott Rifenbark, the project's tech writer. Sadly, Scott passed away early this year. The project is therefore at a cross roads with its documentation and with a need of new contributors and with that, the potential for new ideas and direction.

Ideas

Format Overhaul

Currently the project's documentation is written in docbook, which is a natural choice for a documentation writer, but less so for, say, a developer. To make it as easy as possible for everyone to contribute to the documentation going forward, it would be a good time to convert the raw format of the documentation into a more modern format that is easier to learn. Hopefully this will encourage people who don't usually write project documentation to submit patches and updates. An experimentation has started to evaluate using Sphinx, see https://bugzilla.yoctoproject.org/show_bug.cgi?id=12970. In particular, there is significant potential to improve the way different versions of the manuals for different releases is handled and displayed to users through the website as what is there today is not working for users.

One Voice

Previously the project's documentation was written with one voice. Contributors would suggest updates, and Scott would make sure the flow had a certain uniformity; as though it had all been written in one go, by one person. Moving forward, it's likely the project's documentation updates will likely come from many contributors. It would be great to have someone review the current documentation and future updates with an eye towards maintaining one voice. The project has no documentation of the style of the documentation so establishing some written guidelines for that 'voice' may be part of this too.

Organization

Currently the project's documentation is spread out in several places and formats. There are a number of manuals, some tutorials, a collection of wiki pages, and more. It would be great to see all this information collected together and organized in such a way as to make it easier for people new or experienced with the project to find exactly what they're looking for, quickly. Classify all existing documentation according to various attributes to identify areas that have weak or missing documentation. Fill any gaps in the documentation by creating new docs targeting specific users, tasks, or experience levels; or help motivate the right people to help generate the content. Work with the project's webmaster to present a unified location for all documentation.

Tips and Tricks

The project started a TipsAndTricks project which generated a significant amount of ideas and the start of content which it would be great to turn into sections in the manuals and better document some of these topics. Since the manual sections were never generated, the project stalled but could be restarted and the community would be keen to help with content and ideas.

Update/Release Process

Currently the documentation generation and updating process is quite manual. We believe that integration into our CI and release process is desirable and would be the best way to handle this going forward.

How-to/Tasks Documentation

There was work started to convert some of the manual to a more task oriented/'how-to' approach. [1] has some details but there is potential to significantly expand the task information. It would be great to see the manuals reach this goal of having a much more complete "how-to" task section.