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.
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
