Description
What would you like to be added:
During the v1.30 Release Docs Team retro, facilitated by SIG Docs, we spoke about the opaqueness of the reference docs generation process, which has been continuously opaque for releases from around 1.21/1.22 onwards. Instructions in the Release Docs handbook were incomplete up until recently being completely removed. Release Team subproject leads AND SIG Docs leads want the Release Docs team to be able to execute on this work as part of their Release Team duties in the future.
What we need, at minimum, is for the process to be documented so that any Release or SIG Docs lead can undertake this task.
The timing of reference docs generation is always after the release goes out, as they cannot be generated until the release tag exists (likely several hours later). For each release, the generator must be adapted accordingly, which is done purely by @tengqm at present (we are currently looking for more maintainers of the SIG Docs reference-docs subproject in parallel). The update to the go.mod file is an manual step. At present, Qiming adapts the generators for the new release and proposes PRs directly to the website repo. Generating the references during adaptation takes place in parallel, which is a "simple" way to describe the current process.
Why is this needed:
We currently rely on the knowledge of only a few people to generate our reference documentation each release (specifically Qiming, Rey, and Nate Waddington). We need all current SIG Docs Tech Leads and Release Team subproject owners to learn and create the required docuemntation.
For release v1.31, we will have Kat, Xander, Rey, and Nate work together on learning this work and creating a first pass at documenting the process. After, one of the SIG Docs Tech Leads will co-lead the reference-docs subproject alongside Qiming to help maintain the tooling and to recruit further contributors for future automation and improvements to the subproject.
/cc @reylejano @divya-mohan0209 @tengqm @katcosgrove @salaxander
/triage accepted
/priority important-soon