You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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.
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:
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:
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
The text was updated successfully, but these errors were encountered: