Documentation Review - Revision history

Michael Opdenacker: /* Missing standardization of docs */ Update contents, mentioning the new standards.md file

2022-05-27T16:41:03Z

Missing standardization of docs: Update contents, mentioning the new standards.md file

← Older revision		Revision as of 16:41, 27 May 2022
Line 39:		Line 39:
	Bitbake should probably have its own set_versions.py (script which creates the switchers.js file used on docs.yoctoproject.org) from yocto-docs to show the dropdown menu with appropriate versions		Bitbake should probably have its own set_versions.py (script which creates the switchers.js file used on docs.yoctoproject.org) from yocto-docs to show the dropdown menu with appropriate versions

	=== ~~Missing standardization~~ of docs ===		=== Standardization of docs ===

	We~~'re missing a file explaining all~~ the ~~(yet) unwritten~~ rules ~~applied~~ to the docs.		We have started to describe the rules that we apply to the docs.

	e.g. ~~every variable should be mentioned with :term:`VARIABLE`~~.		See https://git.yoctoproject.org/yocto-docs/tree/documentation/standards.md

	~~e.g. every tool/binary name should be double tick quoted ``like~~ this~~``.~~		Please contribute to this document.

	~~e.g. new images only accepted if clipart/svg~~

	~~e.g. line wrapping at 80 characters~~

	~~etc...~~

	~~See https://lists.yoctoproject~~.~~org/g/docs/message/2044 for a suggestion~~

Quentin Schulz: /* Missing standardization of docs */

2022-04-28T12:43:36Z

Missing standardization of docs

← Older revision		Revision as of 12:43, 28 April 2022
Line 48:		Line 48:

	e.g. new images only accepted if clipart/svg		e.g. new images only accepted if clipart/svg

			e.g. line wrapping at 80 characters

	etc...		etc...

	See https://lists.yoctoproject.org/g/docs/message/2044 for a suggestion		See https://lists.yoctoproject.org/g/docs/message/2044 for a suggestion

Quentin Schulz at 12:41, 28 April 2022

2022-04-28T12:41:04Z

← Older revision		Revision as of 12:41, 28 April 2022
Line 38:		Line 38:

	Bitbake should probably have its own set_versions.py (script which creates the switchers.js file used on docs.yoctoproject.org) from yocto-docs to show the dropdown menu with appropriate versions		Bitbake should probably have its own set_versions.py (script which creates the switchers.js file used on docs.yoctoproject.org) from yocto-docs to show the dropdown menu with appropriate versions

			=== Missing standardization of docs ===

			We're missing a file explaining all the (yet) unwritten rules applied to the docs.

			e.g. every variable should be mentioned with :term:`VARIABLE`.

			e.g. every tool/binary name should be double tick quoted ``like this``.

			e.g. new images only accepted if clipart/svg

			etc...

			See https://lists.yoctoproject.org/g/docs/message/2044 for a suggestion

Rpurdie: /* Outdated migration/release manuals */

2022-04-28T12:38:41Z

Outdated migration/release manuals

← Older revision		Revision as of 12:38, 28 April 2022
Line 29:		Line 29:
	I emitted the idea of using the transition branch for this purpose. It already does smart things like using the directory name to figure out which version of the docs is being built. A migration directory for each release where you only have the migration manual from release n-1 to release n and release notes from release n.		I emitted the idea of using the transition branch for this purpose. It already does smart things like using the directory name to figure out which version of the docs is being built. A migration directory for each release where you only have the migration manual from release n-1 to release n and release notes from release n.
	We don't need to remove references or :term: of older migration manuals once the variables disappear from Bitbake or Yocto glossaries (an issue we recently had). It also directly links to the correct version of Bitbake docs for the links. E.g. if a variable disappears in n+1, we need to remove the ref/term to it in release n-2, n-1 and n migration manuals while they shouldn't be.		We don't need to remove references or :term: of older migration manuals once the variables disappear from Bitbake or Yocto glossaries (an issue we recently had). It also directly links to the correct version of Bitbake docs for the links. E.g. if a variable disappears in n+1, we need to remove the ref/term to it in release n-2, n-1 and n migration manuals while they shouldn't be.

			- RP is worried that the migration/release notes may not be in the release documentation and in any snapshot/tarball of the project. The info there is currently outdated in many cases anyway though sadly.

	=== Yocto versions selection menu on Bitbake docs ===		=== Yocto versions selection menu on Bitbake docs ===

Quentin Schulz at 12:33, 28 April 2022

2022-04-28T12:33:59Z

← Older revision		Revision as of 12:33, 28 April 2022
Line 1:		Line 1:
	Yocto documentation review.		Yocto documentation review.

			== Known issues ==
			=== Outdated migration/release manuals ===

			Release and migration manuals are generated from the docs at a given commit and makes it impossible to be up-to-date. E.g. the migration manual for release tag 4.0 is out of date because the commit used for tagging does not have all fixes present in the kirkstone branch. (it's also a bit of a chicken and the egg problem, requiring a valid commit to tag a release, but waiting on a tagged release to finish the docs). Another example: some fix was sent recently for 3.4 migration manual but it won't make it to 3.4 release unless we manually patch it on yp-autobuilder-helper. It is VERY likely we won't get everything right on a given tag. For most of the documentation it is ok, but migration and release manuals are critical as it's one of the first things people look at (or at least should :) ) when upgrading.

			For now, the default page on docs.yoctoproject.org points to the latest branch release (time of writing: kirkstone) instead of the latest tag (which is the goal), which is unstable (in-between tags, with active development going on).

			see:

			https://docs.yoctoproject.org/4.0/migration-guides/migration-4.0.html is outdated

			https://docs.yoctoproject.org/kirkstone/migration-guides/migration-4.0.html up-to-date

			Also, in 3.1 docs, we only have migration manuals and release notes for <3.1 if I'm not mistaken.

			Requirements (to be discussed):

			- on docs.yoctoproject.org, for any tagged release, at least the latest version of the migration and release manuals from the series should be used,

			- release notes needs to be in the tag/branch of the release. They may be outdated, but it's better than nothing and allows for offline checks,



			Suggestions:

			- [qschulz] having migration manuals and release notes pages common to all versions of the docs. This also shows how far behind a user might be. This is also great when doing a multi-release update, the user can directly go through all previous migration manuals.
			I emitted the idea of using the transition branch for this purpose. It already does smart things like using the directory name to figure out which version of the docs is being built. A migration directory for each release where you only have the migration manual from release n-1 to release n and release notes from release n.
			We don't need to remove references or :term: of older migration manuals once the variables disappear from Bitbake or Yocto glossaries (an issue we recently had). It also directly links to the correct version of Bitbake docs for the links. E.g. if a variable disappears in n+1, we need to remove the ref/term to it in release n-2, n-1 and n migration manuals while they shouldn't be.

			=== Yocto versions selection menu on Bitbake docs ===
			https://docs.yoctoproject.org/bitbake/ shows a version selection dropdown menu with versions from Yocto Project and not Bitbake.

			This is due to https://git.yoctoproject.org/yocto-autobuilder-helper/tree/scripts/run-docs-build?id=91f49091cc8d7f3810a989bc3e7042fc81da21fc#n162

			Bitbake should probably have its own set_versions.py (script which creates the switchers.js file used on docs.yoctoproject.org) from yocto-docs to show the dropdown menu with appropriate versions

Henry Bruce: Created page with "Yocto documentation review."

2017-09-09T04:21:44Z

Created page with "Yocto documentation review."

New page

Yocto documentation review.