Documentation Engineering: Multi-Component Documentation

[g-pavlov]

Documentation Engineering

Milestone stage in #51

Multi-Components Documentation Publishing Platform (DocHub)

Leveraging #50, the next stage is to turn the documentation on the website into a multi-component documentation publishing platform.

• As "New to Gardener", I want to explore, which are the components that the project supports and learn more about them
• As a Gardener Stakeholder, I want to pin the documentation for the particular release of the components that constitute my landscape deployment
• As a "New to Gardener"/Gardener stakeholder, I want to explore components documentation to plan upgrade or adoption of a component in a particular version
• As a Gardener Component Owner, I want to register my component documentation to be published automatically to the website upon its every release
• As a Gardener Component Owner, I want to be responsible for authoring, structuring and compliance of my material with the publishing platform
• As a Gardener Component Owner, I want to preview changes to my component documentation early and before published
• As a Gardener Documentation Website Master, I want to have new component documentation and its releases published in coherence with the established website framework automatically and efficiently

Motivation

The documentation on gardener.cloud currently is Gardener-centric, which serves most of the cases, but it leaves out other components, such as extensions. Their documentation is dispersed all round the org repos and one needs to leave the website to exploring it, which considering 80+ repos (as of now) in different state and purpose is not easy task. Instead, we would like to have a single Documentation Hub (DocHub), a one stop shop for people to find documentation on anything in the project. And we want it to scale and stay future-proof.

Concerns

Process Transparency

While the integration with the publishing platform requires some insight into how to comply with the website rules, so that the result looks coherent, technically it needs to be as transparent as possible. The role of a component owner needs to keep most of its focus on providing documentation structured according to the rules. To put it simply, they do not need to know how their content makes its way from the repo to the website as long as it's there.

Matching website and content versions

Website can and will evolve. Layout and configuration will change. Considering a multitude of versions of component documentation bundles that will quickly explode. A breaking change in the rendering such as deprecation of a shortcode in favor of another will then become an overkill to apply.

It should be possible to maintain older content without changes, if that's acceptable, or stage the migration by changing the site reference when it is convenient to make the move.

UX

Working on the website interface with a multitude of components each with unlimited number of documentation versions is a challenge in terms of user experience. The site layouts need to account for that and present effective pattern for locating a component and a concrete version of a document among many.

Scalable site building

We need a predictable and controlled load on the build process, and within a reasonable timeframe range, and storage volume.

Search index

The component documentation bundle versions need to be ready for indexing by a local search solution or external indexing service such as algolia or google.com.

Change Preview

A concept for preview of changes is necessary to minimize turn round times and provide sufficient idea of how the final change will look like, even if it's partial.

[g-pavlov]

Solution Proposal

• Builds on Gardener component model’s dependencies and Gardener CI/CD mechanisms for notification upon dependency release
• Component providers self-register their components in DocHub by creating a docforge manifest.yaml in a .docforge folder in the component repository root. (similar to the role of the Gardener CI/CD .ci folder and pipeline_definition)
• Upon component release, DocHub builds a microsite for the new version of its documentation with Hugo, and publishes it as navigable content on the website along with the rest of the components, and their versions.
• Published component versions are immutable. Changes are made with new releases of the component - major, minor or patch.
• The platform performs scalable delta updates only. It builds only components that released, and publishes only the microsites for them, and not the whole website.
• Microsites can specify additional metadata, e.g. to reference a particular website configuration to use for their build, a human-readable label and description to use when listed.
• Microsites are integrated in a common frame and theme on the website that includes the top-level navigation of the site and presents a coherent UX
• Local previews of microsites can be performed by component owners before pushing changes, using docker containerized build and publish of a stripped down version of the site containing the common frame and their content, but not other components.
• Microsites need to contribute seamlessly to the site SEO and its analytics solution. For example, a component build in DocHub should include auto-generated sitemap.xml for the new component version and the publishing - its integration with the website sitemap.xml.

UI Mockup

Further details

Please, find further sketches of the process flow, including self-registration and build on release in here

[Kristian-ZH]

Done