Skip to content
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

Cleanup duplications for KVScheduler #20

Open
ondrej-fabry opened this issue May 8, 2019 · 0 comments
Open

Cleanup duplications for KVScheduler #20

ondrej-fabry opened this issue May 8, 2019 · 0 comments
Assignees
Labels
bug Something isn't working discussion

Comments

@ondrej-fabry
Copy link
Member

ondrej-fabry commented May 8, 2019

Ligato Docs currently contain 3 articles named KVScheduler just in the navbar.

The last two seem to have started from same article, but now they are clearly very different due some modifications. We urgently need to clean this up to avoid confusing users.

This issue should also open some discussion about what kind of documenation should be kept at Plugins and Dev Guide.

At the moment the KVScheduler article from Dev Guide contains several different kinds of information:

  • history of KVScheduler
  • basic concepts & terminology
  • API structure
  • REST API reference

I'm sure that this mix of information in single article just overwhelms the reader. Users are looking for specific type of information in the docs at one point in time.

To quote from the article What nobody tells you about documentation that I've shared before:

In fact, it’s extremely hard to maintain good documentation that doesn’t implicitly or explicitly recognise the quadrants of this scheme. The demands of each kind are different from those of the others, so any attempt at documentation that fails to maintain this structure suffers, as it’s pulled in different directions at once.

I think we should define and write down (I started some draft in wiki already) guidelines for writing docs and apply them to current docs.

@chrismetz09 @milanlenco @VladoLavor

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working discussion
Projects
None yet
Development

No branches or pull requests

2 participants