Refactoring documentation

[vlcinsky]

I know, kapitan is a tool of great value. At the same time, I continually struggle with Kapitan's documentation. And I am sure, it harms wider adoption of the tool.

Problematic aspects of existing documentation

The structure is confusing

On https://kapitan.dev/ I see following top level menu items:

• Home
• Getting started
• Support
• Contribute
• Blog
• Documentation
• CLI reference
• Examples
• FAQ

Regarding the order - it often feels wierd:

• why is Support following "Getting started" - One would expect a tutorial here, or How Tos. Support usually comes as one of final documentation parts, not so early.
• why is Contribute so early? This is quite different use case which is often put after one explains usage of the product.
• why is Blog so early? It is usually put apart as a place to provide news
• Documentation - finally we come to the point.
• CLI reference - one would expect to be part of the Documentation.
• Examples - ok. It must go somewhere
• FAQ - possibly good place, but the content is strange - one link to an article in a blog and one hint to use nonexistent "comments facility"

Some topics are missing or incorrect or incomplete

Just two examples:

• Issue Generator contract - how to write my own generator #975 - generator contract not described
• Issue Issue with documentation #953 - "see and example" instruction with forgotten link to actual example

Proposed approach for refactoring

Current Kapitan shows, that real focus and effort go to the product itself but the documentation is lacking priority in development process.

I would propose following approach:

• clarify, what resources are available for refactoring the documentation (current documentation owner if any, paid or volunteer documentation writers available)
• propose new documentation structure. Consider learning from https://diataxis.fr/
• review documentation coverage - which topics are covered and which are missing or incomplete
• agree on steps and priorities
• start refactoring

[ademariag]

hi @vlcinsky , thank you for your suggestions. https://diataxis.fr/ looks very cool.

I am the main person responsible for the (lack of) documentation, and I am currently working (slowly) on improving it, so I appreciate particularly your candor.

Feel free to help us if you want to , and if you haven't already, please join our #kapitan channel on the kubernetes slack.

Also, just to let you know we are meeting tomorrow at 12:00 UK time for the monthly Kapitan Working Group, feel free to join if you want to (details on the slack channel)

[vlcinsky]

@ademariag I am interested in joining the Kubernetes Slack - for this I will probably need an invitation. My e-mail address is [email protected] or I can use my private one, [email protected] which I have bound to my GitHub account vlcinsky.

[ademariag]

I have invited you on [email protected]

[ademariag]

@vlcinsky did some work towards your suggestions. Let me know what you think

[vlcinsky]

Hi @ademariag

Regarding invitation to Slack - it is not working for me:

• no invitation found (spam filter checked too)
• my attempt to login to kubernetes slack workspace ends with "No account found" email stating "It looks like there isn’t an account on Kubernetes tied to this email address."

Regarding After reshuffling top menu items: it looks better now.

Anyway, there are still a few things which seem to me worth to improve. I would be glad to:

• discuss it with you (Zoom or slack telco?). Possible topics to cover:
  • concepts of https://diataxis.fr and how it could apply to existing kapitan docs
• I can try to propose new documentation structure (this subject to my limited time capacity, it can take a week or two)
• I can possibly try to contribute part of the documentation changes myself, if feasible.

[ademariag]

Hi @vlcinsky

Also try this: https://kubernetes.slack.com/signup#/domain-signup

once you are in we can discuss what to do, but yes any help is welcome

[vlcinsky]

@ademariag all my attempts to join the kubernetes.slack.com are failing.

• (1) my [email protected] does not match the expected domain @get-an-invite-at.slack.kubernetes.io as stated at (3) and (4)
• I have tested using my gmail account (2) to login with the same result (using [email protected] account)
• filling the (3) with "jan.vlcinsky" resulted in the same reply.

I would propose to try Zoom, if you send me contact e-mail to [email protected], I would provide you with a Zoom invite. Possible time to meet are:

• today till 15:00 BST or later between 18:30 and 23:00 BST
• Tuesday from 08:00 untill 12:00 BST or between 19:00 and 23:00 BST