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.

- 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

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

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