SeasonOfDocs - Revision history

Nicolas Dechesne: /* Candidate Criteria */

2021-06-02T23:43:16Z

Candidate Criteria

← Older revision		Revision as of 23:43, 2 June 2021
Line 26:		Line 26:
	* a "nice to have" skill would be the ability to read, run, and understand short snippets of python3 and shell code		* a "nice to have" skill would be the ability to read, run, and understand short snippets of python3 and shell code
	* another "nice to have" skill would be the ability to run different Linux distros (e.g. Fedora, openSUSE, Ubuntu) in virtual environments		* another "nice to have" skill would be the ability to run different Linux distros (e.g. Fedora, openSUSE, Ubuntu) in virtual environments
	* willingness to hang out in the #yocto channel on ~~freenode's~~ irc ~~server~~		* willingness to hang out in the #yocto channel on irc

	==Ideas==		==Ideas==

Trevor Woerner: /* Ideas */

2020-04-30T18:43:12Z

Ideas

← Older revision		Revision as of 18:43, 30 April 2020
Line 44:		Line 44:
	===Update/Release Process===		===Update/Release Process===
	Currently the documentation generation and updating process is quite manual. We believe that integration into our CI and release process is desirable and would be the best way to handle this going forward.		Currently the documentation generation and updating process is quite manual. We believe that integration into our CI and release process is desirable and would be the best way to handle this going forward.

			===How-to/Tasks Documentation===
			There was work started to convert some of the manual to a more task oriented/'how-to' approach. https://bugzilla.yoctoproject.org/show_bug.cgi?id=11630 has some details but there is potential to significantly expand the task information. It would be great to see the manuals reach this goal of having a much more complete "how-to" task section.

	===Better Layer Integration===		===Better Layer Integration===
	The Yocto project is organized as a "core" (which is maintained by The Yocto Project) and "layers" (which are maintained by volunteers). Creating an image for a specific device will often require information for the core and information from individual layer components. There is an opportunity to investigate how to incorporate documentation from various layer projects into a unified whole.		The Yocto project is organized as a "core" (which is maintained by The Yocto Project) and "layers" (which are maintained by volunteers). Creating an image for a specific device will often require information for the core and information from individual layer components. There is an opportunity to investigate how to incorporate documentation from various layer projects into a unified whole.

	~~===How-to/Tasks Documentation===~~
	There was work started to convert some of the manual to a more task oriented/'how-to' approach. https://bugzilla.yoctoproject.org/show_bug.cgi?id=11630 has some details but there is potential to significantly expand the task information. It would be great to see the manuals reach this goal of having a much more complete "how-to" task section.

Trevor Woerner: /* Ideas */

2020-04-30T18:42:38Z

Ideas

← Older revision		Revision as of 18:42, 30 April 2020
Line 37:		Line 37:

	===Organization===		===Organization===
	Currently the project's documentation is spread out in several places and formats. There are a number of manuals, some tutorials, a collection of wiki pages, and more. It would be great to see all this information collected together and organized in such a way as to make it easier for people new or experienced with the project to find exactly what they're looking for, quickly. Classify all existing documentation according to various attributes to identify areas that have weak or missing documentation. Fill any gaps in the documentation by creating new docs targeting specific users, tasks, or experience levels; or help motivate the right people to help generate the content. Work with the project's webmaster to present a unified location for all documentation.		Currently the project's documentation is spread out in several places and formats. There are a number of manuals, some tutorials, a collection of wiki pages, and more. It would be great to see all this information collected together and organized in such a way as to make it easier for people new or experienced with the project to find exactly what they're looking for, quickly. Classify all existing documentation according to various attributes to identify areas that have weak or missing documentation. Fill any gaps in the documentation by creating new docs targeting specific users, tasks, or experience levels; or help motivate the right people to help generate the content. Work with the project's webmaster to present a unified location for all documentation. Perhaps run a survey to poll users on their thoughts regarding the usefulness of the current documentation, and generate an actionable report.

	===Tips and Tricks===		===Tips and Tricks===
Line 44:		Line 44:
	===Update/Release Process===		===Update/Release Process===
	Currently the documentation generation and updating process is quite manual. We believe that integration into our CI and release process is desirable and would be the best way to handle this going forward.		Currently the documentation generation and updating process is quite manual. We believe that integration into our CI and release process is desirable and would be the best way to handle this going forward.

			===Better Layer Integration===
			The Yocto project is organized as a "core" (which is maintained by The Yocto Project) and "layers" (which are maintained by volunteers). Creating an image for a specific device will often require information for the core and information from individual layer components. There is an opportunity to investigate how to incorporate documentation from various layer projects into a unified whole.

	===How-to/Tasks Documentation===		===How-to/Tasks Documentation===
	There was work started to convert some of the manual to a more task oriented/'how-to' approach. https://bugzilla.yoctoproject.org/show_bug.cgi?id=11630 has some details but there is potential to significantly expand the task information. It would be great to see the manuals reach this goal of having a much more complete "how-to" task section.		There was work started to convert some of the manual to a more task oriented/'how-to' approach. https://bugzilla.yoctoproject.org/show_bug.cgi?id=11630 has some details but there is potential to significantly expand the task information. It would be great to see the manuals reach this goal of having a much more complete "how-to" task section.

Trevor Woerner: /* One Voice */

2020-04-30T18:36:01Z

One Voice

← Older revision		Revision as of 18:36, 30 April 2020
Line 34:		Line 34:

	===One Voice===		===One Voice===
	Previously the project's documentation was written with one voice. Contributors would suggest updates, and Scott would make sure the flow had a certain uniformity; as though it had all been written in one go, by one person. Moving forward, it's likely the project's documentation updates will come from many contributors. It would be great to have someone review the current documentation and future updates with an eye towards maintaining one voice. ~~The project has~~ no ~~documentation of the~~ style of the ~~documentation so~~ establishing some written guidelines for that 'voice' may be part of this too.		Previously the project's documentation was written with one voice. Contributors would suggest updates, and Scott would make sure the flow had a certain uniformity; as though it had all been written in one go, by one person. Moving forward, it's likely the project's documentation updates will come from many contributors. It would be great to have someone review the current documentation and future updates with an eye towards maintaining one voice. Currently there are no style guidelines for the project; establishing some written guidelines for that 'voice' may be part of this too.

	===Organization===		===Organization===

Trevor Woerner: /* One Voice */

2020-04-30T18:34:26Z

One Voice

← Older revision		Revision as of 18:34, 30 April 2020
Line 34:		Line 34:

	===One Voice===		===One Voice===
	Previously the project's documentation was written with one voice. Contributors would suggest updates, and Scott would make sure the flow had a certain uniformity; as though it had all been written in one go, by one person. Moving forward, it's likely the project's documentation updates will ~~likely~~ come from many contributors. It would be great to have someone review the current documentation and future updates with an eye towards maintaining one voice. The project has no documentation of the style of the documentation so establishing some written guidelines for that 'voice' may be part of this too.		Previously the project's documentation was written with one voice. Contributors would suggest updates, and Scott would make sure the flow had a certain uniformity; as though it had all been written in one go, by one person. Moving forward, it's likely the project's documentation updates will come from many contributors. It would be great to have someone review the current documentation and future updates with an eye towards maintaining one voice. The project has no documentation of the style of the documentation so establishing some written guidelines for that 'voice' may be part of this too.

	===Organization===		===Organization===

Trevor Woerner: /* Format Overhaul */

2020-04-30T18:33:38Z

Format Overhaul

← Older revision		Revision as of 18:33, 30 April 2020
Line 31:		Line 31:

	===Format Overhaul===		===Format Overhaul===
	Currently the project's documentation is written in docbook, which is a natural choice for a documentation writer, but less so for, say, a developer. To make it as easy as possible for everyone to contribute to the documentation going forward, it would be a good time to convert the raw format of the documentation into a more modern format that is easier to learn. Hopefully this will encourage people who don't usually write project documentation to submit patches and updates. An ~~experimentation has started~~ to evaluate using Sphinx, see https://bugzilla.yoctoproject.org/show_bug.cgi?id=12970. In particular, there is significant potential to improve the way different versions of the manuals for different releases is handled and displayed to users through the website as what is there today is not working for users.		Currently the project's documentation is written in docbook, which is a natural choice for a documentation writer, but less so for, say, a developer. To make it as easy as possible for everyone to contribute to the documentation going forward, it would be a good time to convert the raw format of the documentation into a more modern format that is easier to learn. Hopefully this will encourage people who don't usually write project documentation to submit patches and updates. An experiment was undertaken to evaluate using Sphinx, see https://bugzilla.yoctoproject.org/show_bug.cgi?id=12970. In particular, there is significant potential to improve the way different versions of the manuals for different releases are handled and displayed to users through the website, as what is there today is not working for users.

	===One Voice===		===One Voice===

Trevor Woerner: /* Candidate Criteria */

2020-04-30T18:30:55Z

Candidate Criteria

← Older revision		Revision as of 18:30, 30 April 2020
Line 25:		Line 25:
	* it would be very beneficial for this role to know how to use git, at least at a basic level		* it would be very beneficial for this role to know how to use git, at least at a basic level
	* a "nice to have" skill would be the ability to read, run, and understand short snippets of python3 and shell code		* a "nice to have" skill would be the ability to read, run, and understand short snippets of python3 and shell code
			* another "nice to have" skill would be the ability to run different Linux distros (e.g. Fedora, openSUSE, Ubuntu) in virtual environments
			* willingness to hang out in the #yocto channel on freenode's irc server

	==Ideas==		==Ideas==

Trevor Woerner: /* Candidate Criteria */

2020-04-30T18:19:24Z

Candidate Criteria

← Older revision		Revision as of 18:19, 30 April 2020
Line 18:		Line 18:

	* excellent written command of the English language		* excellent written command of the English language
	* ~~ideally~~ you~~'ve worked~~ as a writer, preferably writing technical documentation		* you have experience as a writer, preferably writing technical documentation
	* able to distill "geek ~~gobblty-goop~~" into simple and understandable prose		* able to distill "geek gobbledygook" into simple and understandable prose
			* knowledge of and the ability to use various writing tools and schemes (sgml, xml, sphinx, etc)
			* ability to draw simple but meaningful diagrams, and incorporate them into your writing
			* strong ability to work with and use the Linux command-line
			* it would be very beneficial for this role to know how to use git, at least at a basic level
			* a "nice to have" skill would be the ability to read, run, and understand short snippets of python3 and shell code

	==Ideas==		==Ideas==

Trevor Woerner: /* Yocto Project Season of Docs */ added a "job description" section

2020-04-30T18:12:41Z

Yocto Project Season of Docs: added a "job description" section

← Older revision		Revision as of 18:12, 30 April 2020
Line 14:		Line 14:

	The following mailing list was created to discuss about the Season of Docs project: https://lists.yoctoproject.org/g/season-of-docs/.		The following mailing list was created to discuss about the Season of Docs project: https://lists.yoctoproject.org/g/season-of-docs/.

			==Candidate Criteria==

			* excellent written command of the English language
			* ideally you've worked as a writer, preferably writing technical documentation
			* able to distill "geek gobblty-goop" into simple and understandable prose

	==Ideas==		==Ideas==

Trevor Woerner: /* About */

2020-04-30T18:07:45Z

About

← Older revision		Revision as of 18:07, 30 April 2020
Line 5:		Line 5:

	Richard Purdie, the Yocto Project's lead developer and Linux Foundation Fellow, considers documentation to be one of the cornerstones of this project. The quality and breadth of the documentation is one of the aspects of the project which is appreciated by and commented upon by our users. One of the very first members of that team to work on what became the Yocto Project 10 years ago was Scott Rifenbark, the project's tech writer. Sadly, Scott passed away early this year. The project is therefore at a cross roads with its documentation and with a need of new contributors and with that, the potential for new ideas and direction.		Richard Purdie, the Yocto Project's lead developer and Linux Foundation Fellow, considers documentation to be one of the cornerstones of this project. The quality and breadth of the documentation is one of the aspects of the project which is appreciated by and commented upon by our users. One of the very first members of that team to work on what became the Yocto Project 10 years ago was Scott Rifenbark, the project's tech writer. Sadly, Scott passed away early this year. The project is therefore at a cross roads with its documentation and with a need of new contributors and with that, the potential for new ideas and direction.

			Creating images and GNU/Linux-based distributions takes a wide breadth of knowledge. Even a simple and small image is the combination of dozens of individual software components, each of which has its own quirks and configurations. Each software component is free to choose whatever build system suits its developers, often with little regard for issues concerning cross-compilation. Users who are new to The Yocto Project, and especially new to image creation, are often overwhelmed by its necessary size and scope. Good, comprehensive documentation has always been at the core of The Yocto Project for both new and seasoned users alike.

			The Yocto Project hopes it will be successful in its bid for GSoD. But moreover is hoping to find the right person who will stay on with the project for years to come.

	==Google Season of Docs==		==Google Season of Docs==