Implementing the documentation structure

[oleg-nenashev]

Hello,

I propose to rework the documentation structure in the following way

• README files - top level overviews and quick-start bits. The rest will go to special pages under “/doc” (see below)
  • Top-level README
    • “KLC in a nutshell” - short overview
    • Getting started - Installing and trying out
  • Function Runtime README
  • KLC Operator README
• ROADMAP.md - Overview of the project’s direction and state. Most of the content should be on the linked GitHub project dashboard
• CONTRIBUTING.md - Top-level contributing overview. How to get started, how to find issues, process and governance. The rest will be linked to developer guidelines
• “/doc” - Main holder for the documentation. The documentation will be written in Markdown and grouped by the persona
  • “spec/” - formal specifications associated with the project, including CRDs
  • “admin-guide/” - content for administrators who install and maintainKeptn Lifecycle Controller: Installation guide, Upgrading Keptn, Architecture, Troubleshooting, etc.
  • “user-guide/” - content specific for teams working on projects operated by Keptn, including using Keptn and integrations. Defining Keptn projects, Integrating with KLC, Writing Keptn pre- and post-deployment tasks., eveloping Keptn functions
  • “contributor-guide/” - Set of wiki-ish documentation specific to development of the Keptn Lifecycle Controller itself. Acts as CONTRIBUTING.md extension

See this google doc for the detailed content of each section: https://docs.google.com/document/d/1eVMwZ6EqIKlmui3c7suz_pt9hSDfq_5eiwR8KT9Acw4/edit?usp=sharing

[StackScribe]

So what is the "big picture" here -- that the contents of the /docs directory will be pulled into and published as the doc set when we have tools that can do this? Big thumbs up for that! But it seems to me that some (all?) of the material you are proposing for the README file also needs to be in the docs so how will we handle that? That is also a LOT of information to cram into one README file. I would rather that those bits be under the /doc tree and the README file discuss the software structure, contributing, and such with a link to the documentation for other pieces.

Also, should we follow the Keptn structure and have /content/docs or something, so we have the content directory itself to store non-documentation bits of content that we have?

I'm thinking that it will be easier for all of us if we have some similarity between the structure of the KLC docs, the Keptn docs, and other projects. So that would mean a docs directory rather than doc.

You have admin_guide whereas Keptn has an operate section. I consider admin and operate to be interchangeable terms (I know, technically they are not, but...) but it seems good if KLC and Keptn use the same term. If we like admin better, I could rename the Keptn operate section to be admin

[oleg-nenashev]

There will be eventually as documentation site for that. Waiting for the Docs WG to finalize the New Documentation Engine project :P

Also, should we follow the Keptn structure and have /content/docs or something, so we have the content directory itself to store non-documentation bits of content that we have?

I do not see a reason for that. "content" directory is a common pattern for the website repos so that the content and the engine are separated. We will not have the engine in this repo

I'm thinking that it will be easier for all of us if we have some similarity between the structure of the KLC docs, the Keptn docs, and other projects. So that would mean a docs directory rather than doc.

No strong opinion, fine with "docs"

I could rename the Keptn operate section to be admin

I strongly suggest to focus on a scope for Keptn 1.0 at the moment, not on refactorings

[StackScribe]

We need reference pages! I think you are using the spec/ directory for this but maybe we need a separate reference page section. I'm thinking that the spec may be a basic functional file and the reference pages need to pull that file in (under "Synopsis" header or maybe a "Spec" header) but then have authored information to discuss how to implement things that conform to the spec. I am thinking something about pages similar to the (nascent) reference file for values.yaml (https://keptn.sh/docs/0.19.x/reference/files/values/). Right now, we have a "Spec" section that links to the spec but, when we get the proper tools in place, this should actually suck in that file and display it. The page can then have a link to the actual spec file as it appears in the source tree but the spec itself does not seem appropriate as a stand-alone doc page.

[oleg-nenashev]

I think we need to prototype it. There would be independent reference pages for users and admins, so the Keptn docs structure would not work. I suggest startoing from the spec only, and then improving the UX if just cross references are not enough

[StackScribe]

I would also like an Installation Guide rather than subsuming that information under admin. That gives us more flexibility for dealing with all the permutations of installation in smaller pages and then does not clutter the admin-guide.

[oleg-nenashev]

I would also like an Installation Guide rather than subsuming that information under admin. That gives us more flexibility for dealing with all the permutations of installation in smaller pages and then does not clutter the admin-guide.

There would be many pages under the admin guide. It is just afolder

[thschue]

Most things are fine for me.

At the moment, I would consider combining the admin and user guide (the admin guide might not be very long at the moment). Nevertheless, architectural things might be part of the spec or in a separate folder and not part of the admin documentation. Furthermore, there are no Keptn Projects in the Lifecycle Controller, therefore we should not mention them here.

[oleg-nenashev]

At the moment, I would consider combining the admin and user guide

It might be difficult to separate later, I'd prefer to start with the structure right away even if some guides would be minimum wikipedia-alike entries

architectural things might be part of the spec or in a separate folder

Separate folder looks good to me. I woulnd put it in spec to avoid versioning issues

Furthermore, there are no Keptn Projects in the Lifecycle Controller, therefore we should not mention them here.

It is rather configuration for user's projects. E.g. how do you put Keptn definitions, how do you manage them for branches, etc., etc. It is not "Keptn Project"

[StackScribe]

About Admin Guide and User Guide... I agree with Oleg that it can be messy to separate them later. Also, thinking about the separate audiences is a bit of mental discipline for us. I want the Reference Pages, which will be comprehensive info about all files, commands, API's, etc and for all audiences, which enables us to write guide pages that are targeted to audience/task.