This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- ScummVM
- Technical writer:
- b-gent
- Project name:
- Improve source code documentation via Doxygen
- Project length:
- Standard length (3 months)
Project description
The current ScummVM API (source code) documentation is published here: https://doxygen.scummvm.org/modules.html
It is unfortunately lacking in many areas:
1) There is practically no structure to it, all information is floating on the same level.
2) C++ elements are documented inconsistently with some of them not documented at all. This is something that the organization mentions as one of the main issues.
3) Outdated and deprecated content is still being displayed in the output.
4) Language and usage of doxygen tagging should be made more consistent. A set of rules for this is needed, something that could be a basis for a future documentation styleguide for this project.
5) The doxygen CSS used on this page could be improved to make it more similar to the ScummVM website: https://www.scummvm.org
All of these problems can be tackled during the Season of Docs project.
This Season of Docs application is accompanied by a draft PR that I opened in the project to demonstrate some potential improvements that I propose: https://github.com/scummvm/scummvm/pull/2361 See the description there for some details about what it contains and to view the diff.
This is roughly what the PR involves:
1) I think what is most confusing right now for potential new contributors, and generally everyone who views the current API doc, is the lack of structure. Introducing structured API documentation would improve readability, findability, and, consequently, usability of the docset. That's why my PR introduces doxygen groups to all header files in the 'common' folder. With this new structure, if someone wants to find docs for OS-related API (for example), they can easily find it in the navigation.
2) A new doxygen configuration file is set up to enable building this documentation.
3) A 'links.doxyfile' file from which all links used throughout the docset can be single-sourced. A useful mechanism when working with doxygen.
4) A modified doxygen CSS. This is currently taken from another open-source project and is only a starting point. Ideally, the look-and-feel of the doxygen page should be more or less consistent with the ScummVM web page.
What the PR does not cover but definitely needs to be worked on is the content itself. By that I mean identifying the essential parts of code that are not documented, the ones that are not sufficiently documented, or the outdated parts of code that should be removed from documentation. As I have not worked in the project before, guidance from a mentor will be needed to achieve this.
Of course, whether we implement anything from the PR is up to discussion with the organization. My idea was that actions speak louder than words so I decided to show what I can do instead of just describing it in the application.
The organization has provided the following rough timeline for this project: Week Main task Week 0 (Before 9/14) Proposal discussion & reviews Week 1 (9/14) Doxygen build set up Week 2 (9/21) Refresh of Doxygen skin (low priority) Week 3 (9/28) Common code - OSystem, FS, Data Structures, Strings, etc. Week 4 (10/05) Common code - Continued Week 5 (10/12) Engines - Common code & sample engine Week 6 (10/19) Graphics Week 7 (10/26) Audio Week 8 (11/02) Video, Images Week 9 (11/09) Backends - Platforms, Graphics, Events Week 10 (11/23) Backends - Continued Week 11 (11/30) Project summary and submission
The only change I would propose is start off by working on the structure, as already mentioned. This can be done in weeks 1 & 2, along with the doxygen build setup (which is largely done already) and Doxygen skin refresh. After that, I agree that it makes most sense to go through the different areas one by one with the mentor to identify problems and improve the doxygen documentation.
I see this a standard-length project but I'm sure there are other improvements related to API documentation that can be done after the GSoD project finishes. For example, coming up with a documentation styleguide and adding it to the wiki, so that contributors are aware how they should document the code that they are adding.
I would gladly help with tasks like this after GSoD is over. I am sure ScummVM could use a technical writer who will make sure that its API doc is of good quality and usability. I can also see that there are other future doc projects that I could help you with, like creating a guide on how to work with plugins.