layout: post title: “gem5 joins Season of Docs!” author: Bobby R. Bruce date: 03-05-2020 categories: project
We are pleased to announce that the gem5 project will be participating in this year's Season of Docs. Season of Docs is a program, run by Google, with the goal of fostering collaboration between open source projects and technical writers.
In this blog post we shall outline who we are and what kind of projects we are looking for technical writers to undertake. During the exploration phase (May 11th -- June 8th), we shall begin collaborating with technical writers to flesh-out project ideas, with the goal of having a technical writer join us later in the year to undertake their proposed project.
More general information on Season of Docs can be found at https://developers.google.com/season-of-docs.
Who are we?
gem5 is an open source computer architecture simulator. The tool is used by a number of organizations from university research labs to large industrial players such as Google and ARM. While we have been successful in developing a well engineered and popular product, documentation has been left to software engineers with little technical writing experience. We therefore wish to mentor a technical writer to improve, and expand our documentation.
The gem5 project is highly collaborative, and as such we accept contributions from many individuals across the world. As a technical writer, you would be joining this community, which we hope you'll find a rewarding experience.
Interested?
For those interested in applying, we'd advise first looking through our current documentation, in particular our Learning gem5 tutorial, which should give the reader a step-by-step guide on how to setup and run gem5. We would then like to hear suggestions from technical writers on how best our documentation may be improved.
We have noted below some projects ideas. These are by no means final. We expect an applicant to use these as starting points in order to find interesting work within our project. As we want to utilize technical writing expertise as fully as possible, we encourage technical writers to speak up and reach out if if they have any suggestions. It will be our role, as mentors, to give technical writers the context needed to refine these ideas into something of use to the gem5 community.
We do not expect technical writers to fully understand the ins and outs of the gem5 project. In fact, we want technical writers to use their naiveté to their advantage. Our documentation has been written by those with familiarity to the project. We thereby believe a “fresh pair of eyes” would be of benefit in many areas. A new technical writer within the gem5 team should be able to identify “pain points” in our documentation and help us improve them.
Project Idea: Audit of current documentation
Our documentation has been developed over a long period of time, by different people, with different goals. We therefore do not have a good understanding of what areas of gem5 are documented sufficiently, and which are not. An audit of our current documentation, and what needs further action, would be of great benefit to the community. We can then generate a plan on how to improve our documentation moving forward.
Project Idea: Beginner's Guide Documentation
At present our Learning gem5 tutorial documentation is our “entry point” for beginners to use gem5. We are unsure if this documentation is sufficient, whether it should be expanded upon, or if it should be replaced with something more concise. In this task we are looking to have documentation which will improve how we introduce people to the gem5 project.
Tangentially to this, our project regularly has new contributors, many of whom need taught how to follow our contribution procedures. Typically we direct wannabe contributors to our contribution guidelines and our CONTRIBUTION.md document. As with our Learning gem5 documentation, we would like this investigated and improved upon if need be.
Project Idea: Improve Source-code Documentation
We currently document our codebase through Doxygen. Like other areas of our documentation, our Doxygen documentation has been developed by many people, over many years, thereby leaving much of it written in an inconsistent manner. Furthermore, many areas of the code-base are entirely undocumented. This project would in-part be an audit of what we have, then development of a plan for improvement. We would also not be opposed to a technical writer beginning work on this plan.
The source for gem5 can be found at https://gem5.googlesource.com/public/gem5/.
Project Idea: Improve the documentation website
At present, our documentation is created in a Markdown/Jekyll website. We have came across some limitations with this. In particular, is not easily navigable. Those technical writers with some web-dev/Jekyll experience would be of great use in coming up with an alternative way to present our documentation --- new layouts, new styles, etc.
The source for our website can be found at https://gem5.googlesource.com/public/gem5-website/.
Mentors
A technical writers working within gem5 will be mentored by Dr. Bobby R. Bruce and Prof. Jason Lowe-Power, both of who are situated in the University of California, Davis. Please take note of the California time-zone (assume standard 9AM to 5PM work hours) and how this would work for you. We are willing accept applicants from anywhere in the world. Work does not need to occur during California work hours, but virtual meetings will be regular.
If interested in working on gem5, please contact Dr. Bruce at “bbruce -at- ucdavis.edu” during the Season of Docs exploration phase (May 11th -- June 8th). Dr. Bruce can help you flesh out your ideas prior to submitting an official application. More information on the Season of Docs application process can be found on the Season of Docs website.