Season of Docs: Project Report - Launch a Documentation Portal

 Project report: Launch a documentation portal

•  The original proposal is available here.

•  The finished project, which will remain unchanged, is available here.

•  The live documentation is available here.

•  Pull requests available here .

The objectives

The objectives, as set out in the project proposal:

1.  To produce high-quality, versioned end user documentation by consolidating large amounts of information from disparate sources and re-writing information for clarity, consistency, and completeness. Documentation should be easy to understand for beginners, without being patronizing to tech-savvy users.

2.   To create a documentation portal using a static-site generator.

3.  To future-proof end user documentation by creating templates and detailed how-to instructions for future open source contributors.

The outcomes

The completed documentation portal comfortably meets all the objectives:

•  It is easy to follow, easy to navigate and pulls a large amount of previously disparate information into one place. 

•  It is a complete reference for the ScummVM end user, and is a vast improvement on what was available before. 

•  Templates for platform pages and settings pages are included in the documentation source code, with detailed technical writer contribution instructions now included in the Developer Central section of the ScummVM wiki. The mentor(s), in consultation with the other developers, are in the process of creating guidelines around minimum documentation requirements for new features in future releases. This will ensure that the documentation remains up to date. 

The process

Choosing the platform:

After experimenting with various static-site generators as part of the initial proposal process, the decision to use Sphinx and Read the Docs was a relatively simple one to make. By using reST we have functionality not found in some of the other Markdown-based generators, and the clean look and feel of the Read the Docs theme sealed the deal.

Creating the content:

The original plan was to start by asking developers for platform-specific information, but in the end we decided to focus first and foremost on how to get a user up and running on the basic computer setup— the install, how to use ScummVM, and how to play games—essentially the user manual. 

The other main area of focus was the multitude of settings, accessible both through the GUI and the configuration file. I wrote supporting reference documentation for aspects of the more confusing settings, namely audio and graphics.  

Platform-specific pages were last on the priority list. In consultation with the mentor(s) and developers, I developed a template for all future platform documentation. The platforms that are documented are complete, however there are some supported platforms that are not yet documented due to the inability to get information from developers within the project time frame. 

Because we rearranged the focus of the project somewhat, I revised my timelines on a weekly basis, with projected timelines for the next 2 weeks documented in my blog posts. This seemed to work well.

Throughout the project I had planned to use the wiki extensively to help inform my writing, however this ended up being one of the major challenges I faced. The wiki was either so far out of date, or so confusing, that a lot of the time I was better off asking developers or experienced users for information than using what was already there. In many cases I think this facilitated a better outcome, since I went into it without too many preconceived ideas on the structure or content of the document I was trying to write. 

The wiki will be updated, and redundant information removed, only once the portal is finalised and live. With that in mind, this will happen only after the end of the Season of Docs development period. 

Deciding on the structure:

One part of the portal that was a challenge for me, right up until the end, was finding the best way to structure the documentation. Arguably you can have the best information in the world, but if it’s not easy to find and use then it’s not much help to the user. In the end I decided against my initial proposal structure, since there ended up being too many grey areas causing confusion (specifically in the platform pages, since these also include install instructions!). Overall I’m very happy with the final structure and I think it works well. 

Post-GSOD actions

Everything contained in the documentation portal is complete as it is, and the to-do list items below do not affect the usability of the portal.

To-do:

•  Remove redundant information from the ScummVM wiki, now that the portal is live. 

•  Move game-specific information from the existing Readme to the individual game wiki pages. Game-specific information is outside the scope of the documentation portal. 

•  Document any outstanding supported platforms.

Final thoughts

This project has been an absolutely fantastic experience for me, and I’m so thankful for the ScummVM team and for Google for providing me with this amazing opportunity. Thanks again to everyone who patiently answered my questions over the last few months, I couldn’t have done it without you. I trust my contributions will add value to the ScummVM project, and I’m excited to have my work out there, hopefully making the game playing experience just that little bit easier. I plan to stay on after the end of Season of Docs to continue to offer my writing services to the ScummVM project.