-
Notifications
You must be signed in to change notification settings - Fork 56
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[SPIKE] Documentation Structure #1720
Comments
Relevant documentation: https://docs-guide.readthedocs.io/en/latest/structure/ |
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. 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. |
Some thoughts on organization: remove redundant content remove Getting Started and move content into Installation Guide, can have a link under Installation to call out quick start section Installation guide User guide Why is the operators guide separate from the user guide? Is this a different audience? |
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:
Ideas discussed:
Questions discussed
Ideas to further discuss:
Questions to further discuss
Issues to create:
Structure proposal User Documentation
Community
Dev Guide - link in the CONTRIBUTING.md
|
Tickets created:
|
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
It's not very clear what are the user interfaces of VDK. Could it be made clearer.
etc.
The text was updated successfully, but these errors were encountered: