website: Improved Season of Docs blog post
Some points have been made clearer, some grammar errors have been fixed,
and some phrasing has been improved.
Change-Id: I982defe1c71cd9d8012d0507a4b6dc943d55f382
Reviewed-on: https://gem5-review.googlesource.com/c/public/gem5-website/+/28647
Reviewed-by: Bobby R. Bruce <bbruce@ucdavis.edu>
Maintainer: Bobby R. Bruce <bbruce@ucdavis.edu>
Tested-by: Bobby R. Bruce <bbruce@ucdavis.edu>
diff --git a/_posts/2020-05-03-season-of-docs.md b/_posts/2020-05-03-season-of-docs.md
index b9bd8c2..349ca06 100644
--- a/_posts/2020-05-03-season-of-docs.md
+++ b/_posts/2020-05-03-season-of-docs.md
@@ -15,7 +15,7 @@
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 collaboration with technical writers to
+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.
@@ -45,25 +45,26 @@
best our documentation may be improved.
We have noted below some projects ideas. These are by no means final. We
-expect a technical writer to use these as starting points in order to find
-interesting work within our project. We want to utilize technical writing
-expertise as fully as possible. Therefore, we encourage technical writers to
+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 you the context needed to refine these ideas into something of
-use to the community.
+mentors, to give technical writers the context needed to refine these ideas
+into something of use to the gem5 community.
-While you will be new to the project, we want to encourage you to use this
-naiveté to your advantage. Our documentation has been written by those with
-familiarity to the project. We therefore believe a "fresh pair of eyes" would
-be of benefit in many areas. A new technical writer to the gem5 team should be
-able to identify "pain points" in our documentation and help us improve them.
+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
+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.
@@ -78,8 +79,8 @@
gem5 project.
Tangentially to this, our project regularly has new contributors, many
-of who need educated on how to follow our contribution procedures. Typically
-we direct wannabe contributors to our [contribution guidelines](
+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/master/CONTRIBUTING.md)
document. As with our Learning gem5 documentation, we would like this
@@ -93,19 +94,19 @@
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 take the pattern of "audit, refactor, and expand". We hope a
-technical writer would be able to highlight areas for improvement and carry out
-these documentation improvements within our codebase.
+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
+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.
-The setup, at present, is not easily navigable. Those technical writers
-with some web-dev/Jekyll experience would be of use in coming up with an
+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
@@ -113,12 +114,18 @@
# Mentors
-Technical writers working within gem5 shall be mentored by
+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
+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.
-During the season of docs exploration phase (May 11th -- June 8th) you should,
-contact Dr. Bruce at "bbruce -at- ucdavis.edu" to explore your ideas then
-submit an application to Google. More information on this can be found on the
-[Season of Docs website](https://developers.google.com/season-of-docs).
+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).
