Shoulder.dev Logo Shoulder.dev

Documentation Standards

Use the following context, video list and articles to create a informative and comprehensive summary learning action plan for software developers on their chosen subject.

The target audience are "expert developers, with experience of CNCF projects as a end-user". The goal is to create an easy to follow learning summary with visible progress points. Include Learning Exercises at the end as example projects/challenges to continue learning with. Indicate which URLs where used for the facts or recommendations as footnotes ^#, starting at 1

Section 1: Use the context below to create a long comprehensive summary of the subject based on information provided. Only use the content provided to create the output. Don't say it's a summary. Act like it's the full output and these are the key points to know.

Output as short sentences and bullet points to make it easy to read. Reorganize the sections as required to make it easy to read. Make it motivational.

Section 2: Output a list of recommended videos and articles to watch/read in order. If it's not important to learning topic based on title/description, remove it. The order should be informative and motivational. Vary the language used to make it interesting.

Section 3: Provide a Relevant Code Snippet(s) to use as a reference. Use the code provided in the context below as a reference. If no code is provided, output "No example available".

The format should be in Markdown like this. Important to use titles provided:

"""

Background:

Sentences...

Key Points:

Learning Action Plan:

  • Step:
  • Why:
  • Action - Read, Execute, Practice, Watch, Interact:

Learning Exercises:

Recommended Watching/Reading Order:

  • Article ^#
  • Video ^#

Relevant Code Snippet(s):

Code
  

"""

Content To Use:

Subject: "Documentation Standards"

Videos/Articles: 202005-version-documentation 202005_version_documentation.md

Context: https://thanos.io/v0.21/proposals/202005_version_documentation.md and answers that are frequently asked by users. How do you specify what part of the docs you want to version without cloning every file? docs.yaml We hope to have a single, flexible configuration file ( docs.yaml ) that will help the developer in specifying what part of the docs they need without cloning all the docs. We could have this as a single file on master. The config file will look like this: default:

https://thanos.io/v0.21/proposals/202005_version_documentation.md containing a list of versioned docs consisting of both the latest and older versions. Proposed Solution 1. Version Picker Currently, the documentation resides under the docs/ folder of the Thanos repository. It is built by Hugo. It will have a proper drop-down menu just like the Prometheus website’s drop-down menu , which will enable proper versioning. This user-facing tool will be built using HTML and CSS. 2. Documentation Structure We want to propose a method called “Directory Sub Branching”. Directory Sub branching means creating different sub branches in the versioned folder of the Thanos repository. Since the current architecture of the Thanos website is this: |- archetypes

https://thanos.io/v0.21/proposals/202005_version_documentation.md As a Thanos developer, I don’t want to store duplicated docs in a single repository version. User Story (Previous release) As a Thanos developer, I want to be able to fix docs for an individual previous release. As a Thanos user, I want to be able to read docs for older versions of Thanos. Use Case Users Thanos developers, Hugo developers, and general users. Precondition The user visits the Thanos documentation page. Basic Course Of Events The user indicates that the site is to show a list of docs (both latest and previous releases) by clicking the version picker (dropdown). The site responds by displaying a list of versions allowing the user to make a selection. The user makes a selection and the required docs are rendered on the page/site. Postcondition The site now has a version picker containing a list of versioned docs consisting of both the latest and older versions. Proposed

https://thanos.io/v0.21/proposals/202005_version_documentation.md NOTE: tmp directory is not committed, just temporarily built. The current version of docs lives in the master folder 3. Building a versioning plugin Creating a plugin that can automate these processes would save us a lot of development time and stress. This approach promises to be useful when it comes to versioning different release in the Thanos website. Workflow The developer makes all the necessary edits in /docs on master. The developer proceeds by committing a new release (i.e Release 0.x). CI run some make web or make web-serve command. Before anything, CI generates the docs and places them in a versioned tmp folder. the rest of the web command is executed. NOTE: generated docs are not committed, just temporarily built. FAQ This section consists of some important questions and answers that are frequently asked by users. How do you specify what part of the docs you

https://thanos.io/v0.21/proposals/202005_version_documentation.md What would the plugin look like? CLI ( make generate-versioned-docs ) What is the plan in terms of plugin placement? We hope to start in the Thanos project and then move the project outside to a separate repository. How we do fixes to release docs for older release, e.g. v0.12, work? We will edit the particular release (release-0.12) branch and add a commit. The then tool fetches the latest commit on this branch and uses it to generate the docs. We expect to fetch docs for minor releases without breaking them with patches. We encourage immutability across all our release tags in Thanos. How does the tool discover the releases for fixes? With a regular expression. Instead of the developer manually checking out the individual release branches, the tool handles it for them by using a regex to select and clone valid release branches. The config file for the tool will have a