Proposal to improve the documentation

[AxiomSamarth]

What would you like to be added:
Improve the documentation to fulfil the needs of both developers and endusers. This doc here needs to be updated nicely and then we can think about making it a standard across the MCM for all providers.

Begin with content for endusers and below could be the action items:

• Define standard grammar for documentations in MCM context
  • For example:
    • Uniformity of definitions across all documentations. E.g: The definition of MCM should be common in its every occurrences across all repositories.
    • Usage of camel case format while referring to the MCM's Customer Resource objects like MachineDeployment (same as K8s standard way of naming the CRs)
    • Avoid passive voices and conjuctions like 'that' to keep the sentences as crisp and short as possible.
    • Avoid pronouns. Documentation should be a doc and not a dialogue exchange :P
    • Like this, see there is a documentation guideline already in place or create one.
• Create the table of content
• Add content as granular as a tabular explanation of the
  • MachineClass
  • MachineDeployment's fields with mention of the mandatory fields and optional fields in a way to understand all the configurable knobs (or the flags) and their significance (or functionality) and others on the similar ground as above
• Common issues (FAQ which is already there) and debugging methods/fixes

Why is this needed:
This will make it easier for the consumers to adopt and employ quickly.

[AxiomSamarth]

The Standard Grammar or the documentation standards for MCM

• The Custom Resource objects shall be in Pascal Case. Just like any other Kubernetes resource. For example, MachineDeployment, MachineSet, Machine, MachineClass.
• Avoid passive voice, conjunctions like 'that' to keep sentences simple and crisp.
• Avoid pronouns. Documentations should be a doc and not a dialogue exchange.
• Avoid usage of the finite article 'the' before proper nouns.
• Avoid adverbs (especially words that end with 'ly'). Most of the times, there will be an alternative word for them.
• Convey the content in present tense, future tense and associated tenses. Avoid past tense.
• Capitalise the titles.
• Double check spelling, grammar and punctuation.
• List of items where sequence needs to be honoured, use numbered lists/ordered lists. List of items where sequence need not be honoured, use unordered lists/bullet points.
• Uniformity of definitions across all documentations. E.g: The definition of MCM should be common in its every occurrences across all repositories.
• All figures need to have alternate texts and captions with figure numbers.

PS - 'Avoid' something does not mean we rule it out. It means we minimize. And the list shall be appended with new ones as and when we find a good practice.

[AxiomSamarth]

Vedran's suggestion - To have the documentation different to address the needs of different personas. Also, try to modify the docforge to work that way (fetch different page for operator, different for the developer and different for other end user). Discuss this with Ashwani.

[AxiomSamarth]

Proposal for Table of Contents

Machine Controller Manager

• Overview
• Design of MCM
  • Design Principles
  • Objects of MCM
    • MachineClass
    • Machine
    • MachineSet
    • MachineDeployment
    • Secret
  • Associated Controllers of MCM
    • MachineDeployment Controller
    • MachineSet Controller
    • Machine Controller (Depcreated)
    • Safety Controller - Overshooting logic only
• Working of MCM
• Specification
  • Schema
    • MachineClass
    • Machine
    • MachineSet
    • MachineDeployment
• FAQ

Machine Controller Manager Provider Azure

• Fundamental Design Principles
• Associated Controllers of MCM
  • Machine Controller (Depcreated)
  • Safety Controller - Orphan VM collection only
• Specification
  • Schema
    • ProviderSpec
    • Secret
• Usage of Azure OOT
  • Running Machine Controller for Azure
  • Running Machine Controller Manager
  • Managing the machines with declarative updates
• Errors and Meanings
• FAQ

[AxiomSamarth]

cc: @prashanth26 @amshuman-kr @ashwani2k

I request your feedback on the above structure of the document (which is intended to serve the devops/operator/admin personas). I have tried to keep it pretty generic so that the Machine Controller section can be extended to other providers as well.

Few more points for better comprehension of how I am seeing it

• The schema would look something like this
• The schema for MachineDeployment, MachineSet, Machine and MachineClass objects are included under MCM object specs and the provider specific ProviderSpec and Secret are included under Machine Controller section. So that they can be updated accordingly in other providers' docs.

I am specifically looking for some comments on Errors & Meanings section. Because, we do not have explicit HTTP responses as such. I am thinking if we can cover the common errors in FAQ.

[prashanth26]

The proposed TOC looks good to me. I have made minor changes above - #16 (comment).

I am specifically looking for some comments on Errors & Meanings section. Because, we do not have explicit HTTP responses as such. I am thinking if we can cover the common errors in FAQ.

I hope this doc is detailed enough for the error codes. Feel free to update this doc to refine the content to make it more consumable.

Also for the schema was wondering if we can have some autogeneration for the fields and expected values based on the types.go? We can have comments that translate to the definition. I have seen projects doing this, not sure how easy this is to acheive.

[AxiomSamarth]

Thanks for the reviews, @prashanth26.

Also for the schema was wondering if we can have some autogeneration for the fields and expected values based on the types.go?

I will research a bit around this and see what I can find 😄

[AxiomSamarth]

gen-crd-api-reference-docs is used to auto generate the docs from the CRD file and description is fetched from their comments.

Next step is to structure the package & create a dedicated module for APIs in a way to avoid cyclic dependencies. Reference PRs for the same are as below -

• Create a dedicated module for api etcd-druid#169
• Create separate api module hvpa-controller#85

[himanshu-kun]

/close in favor of gardener/machine-controller-manager#770