_posts/2020-05-03-season-of-docs.md - public/gem5-website - Git at Google

 ---
 layout: post
 title:  "gem5 joins Season of Docs!"
 author: Bobby R. Bruce
 date:   03-05-2020
 categories: project
 ---

 ![](/assets/img/season_of_docs.png)

 We are pleased to announce that the gem5 project will be participating in this
 year's [Season of Docs](https://developers.google.com/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](http://www.gem5.org/documentation/), in particular our
 [Learning gem5](http://www.gem5.org/documentation/learning_gem5/introduction/)
 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](
 http://www.gem5.org/documentation/learning_gem5/introduction/) 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](
 http://www.gem5.org/contributing) and our [CONTRIBUTION.md](
 https://gem5.googlesource.com/public/gem5/+/refs/heads/stable/CONTRIBUTING.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](http://www.doxygen.nl/).
 Like other areas of our documentation, [our Doxygen documentation](
 doxygen.gem5.org) 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](http://www.gem5.org/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](https://www.bobbybruce.net) and [Prof. Jason Lowe-Power](
 https://faculty.engineering.ucdavis.edu/lowepower/), 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](
 https://developers.google.com/season-of-docs).
	---
	layout: post
	title: "gem5 joins Season of Docs!"
	author: Bobby R. Bruce
	date: 03-05-2020
	categories: project
	---

	![](/assets/img/season_of_docs.png)

	We are pleased to announce that the gem5 project will be participating in this
	year's [Season of Docs](https://developers.google.com/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](http://www.gem5.org/documentation/), in particular our
	[Learning gem5](http://www.gem5.org/documentation/learning_gem5/introduction/)
	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](
	http://www.gem5.org/documentation/learning_gem5/introduction/) 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](
	http://www.gem5.org/contributing) and our [CONTRIBUTION.md](
	https://gem5.googlesource.com/public/gem5/+/refs/heads/stable/CONTRIBUTING.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](http://www.doxygen.nl/).
	Like other areas of our documentation, [our Doxygen documentation](
	doxygen.gem5.org) 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](http://www.gem5.org/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](https://www.bobbybruce.net) and [Prof. Jason Lowe-Power](
	https://faculty.engineering.ucdavis.edu/lowepower/), 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](
	https://developers.google.com/season-of-docs).