[SPIKE] Documentation Structure

[exalate-issue-sync]

In order to solve #1569] we need to have some specific implementation ideas and steps. The story lists fairly well the problem but we need also solutions. 

This spike is to research how best to address the issue around documentation structure. 

Some things to improve noted are 
Around examples: 

• We have currently 2 pages about Examples - [https://github.com/vmware/versatile-data-kit/wiki/Examples] and the README in examples folder [https://github.com/vmware/versatile-data-kit/tree/main/examples] 

• The page quality is not the same as in the main README. It would be nice to have some more visualization to make it easier for users to find what they need

• Going from main readme to some example is longer time than it should. 

So specific story could be 

• Create standards for documentation pages 
• Re-write the main example/tutorial page to meet this standard (and remove the 2nd one)

It's not very clear what are the user interfaces of VDK. Could it be made clearer. 

etc. 

[zverulacis]

Relevant documentation: https://docs-guide.readthedocs.io/en/latest/structure/

[zverulacis]

The idea is that, at the moment, most of the documentation in the Wiki repeats itself and could be structured better. I was thinking of mindmap-like documentation that could be split into components, and each part could have its own examples.
This task requires some brainstorming about potential solutions, I'm open to suggestions if you have any, and then we could generate some tickets as potential solutions to implement.

Now we have put the components into the README. I think it could be a good start. Each image could be a link to its documentation.

I don't think this could be a way to solve the repetitiveness and bring more structure. It's just an idea at the moment.

[gary-tai]

Some thoughts on organization:

remove redundant content
- What Problem Does Versatile Data Kit Solve? > link to README

remove Getting Started and move content into Installation Guide, can have a link under Installation to call out quick start section

Installation guide
-include getting started/quick start content
Installation guide
-Quick Start

User guide
- include interfaces in this section as it's reference content. Maybe format the interface content as a table.
User guide
-Examples (remove hello world, it's already in quick start)
-Interfaces

Why is the operators guide separate from the user guide? Is this a different audience?
- A lot of setup before we get to installing the control service.

[zverulacis]

As part of the solution for this ticket, a meeting was set to discuss the possible options for cleaning up and structuring our existing Wiki pages.

Meeting agenda:

• Go through the existing ideas and discuss each
• Come up with a new list of ideas
• Create Action items

Ideas discussed:

1. The components in the README. Each image could be a link to its documentation.

2. remove redundant content - What Problem Does Versatile Data Kit Solve? > link to README

3. Remove Getting Started and move content into Installation Guide, can have a link under Installation to call out quick start section

Questions discussed

• What's the purpose of the README vs. Wiki
• Purpose of Wiki vs. VEP

---

Ideas to further discuss:

5. Proposed structure improvements:

• Installation guide

• include getting started/quick start content

• Installation guide - Quick Start

• User guide - include interfaces in this section as its reference content. Maybe format the interface content as a table.

• User guide - Examples (remove hello world, it's already in quick start) - Interfaces

Questions to further discuss

• Why is the operator's guide separate from the user guide? Is this a different audience?
• A lot of setups before we get to installing the control service.

---

Issues to create:

1. Generate a sitemap/mindmap proposal for the documentation
2. Move Developer Documentation to the CONTRIBUTING.md from the Wiki.
3. Add a section for the USER components - and link to each image in the README.md file -link each of the components to its Wiki
4. Move other user-relevant READMEs to the Wiki
5. Merge the Introduction page and main README file and rename the Introduction - Home (contents of the Wiki)
6. Remove the repeating info from the Wiki:

• Installation instructions should be removed from the Getting Started - link Installation page
• Remove Overview from the User Guide
• Move Dev Guide and Documentation guide to the repo - in the CONTRIBUTING.md
• Getting started shouldn't repeat the installation page and should reflect what's on it - remove the example
• Remove Dev Guide from Wiki
• Remove markdown tips and tricks from DevGuide
• Delete Dev How to from Dev Guide
• CICD.md in the repo in https://github.com/vmware/versatile-data-kit/tree/main/support link in the CONTRIBUTING.md
• Link the best practices to CONTRIBUTING https://github.com/vmware/versatile-data-kit/wiki/How-to-prepare-a-new-PR
• Basically, link all the relevant pages from the Dev Guide to the CONTRIBUTING.md
• Documentation guide can be linked in the CONTRIBUTING.md and removed from the main Wiki page

Structure proposal

User Documentation

1. Home
2. Installation
3. Getting Started
4. Examples
5. Dictionary

User Guide

1. ..
2. add components documentation

Community

1. Resources
2. Community meetings

Dev Guide - link in the CONTRIBUTING.md

1. Coding Standard
2. PR best practices
3. CICD
4. Dependencies licensing

[zverulacis]

Tickets created:

1. Generate a sitemap/mindmap proposal for the documentation and Wiki #2145 - mindmap for the wiki
2. Move Developer Documentation from the Wiki to the CONTRIBUTING.md #2146 - remove Dev Guide from Wiki
3. Documentation: add a section for the USER components - link each of the components from README to its Wiki #2147 - document components
4. Move user-relevant READMEs to the User Wiki #2148 - move user-relevant READMEs to Wiki
5. Documentation: Introduction page - merge with main README file and rename the Introduction - Home (with contents of the Wiki) #2149 - Introduction page
6. Remove the repeating info from the Wiki #2150 - Remove the duplicating information