versatile-data-kit icon indicating copy to clipboard operation
versatile-data-kit copied to clipboard
verified publisher icon vmware

Wiki: team feedback

Open zverulacis opened this issue 2 years ago • 3 comments

While the restructuring of the Wiki is in progress, some feedback on the structure is necessary to make it incremental:

Please review and comment on the current state of wiki.

I'd need you to:

  1. Give feedback about the Home page
  2. General Structure of the Wiki
  3. Each page in the structure
  • relevance (should it exist?)
  • content (does it make sense?)
  • location (is it in the right place?)
  1. Any comments on improvements, what's missing?

This ticket is to gather and implement the suggestions.

Acceprance criteria:

  • at least 2 people have reviewed and provided feedback. Changes as per the feedback are implemented.

zverulacis avatar Feb 08 '24 11:02 zverulacis

Home page:

I really like the home page. My only problem is with those anchor buttons. They have a very jumpy feel. But I still think it is better with them in than without it.

General Structure of the Wiki:

This is more a general comment about wikis in github. Whenever I am working(contributing to/or just reading) with a github project I always clone it locally. If I'm looking for docs/how tos/etc.. I will always search the repo in intellij for the keyword etc I am looking for.

When docs are in the wiki I don't find them.

This has actually happened me on a number of occasions in our repo. Where I was looking for the docs on how to debug a job in intellij and couldn't find the docs.

This is also a general complaint about github wikis. But its a bit weird that there is a pages section before the content layout part. but I much prefer the feel of looking for a page in the pages section. Can we have a consistent layout between the two? Or even better get rid of the side bar and just use the pages part?

I would change dictionary to glossary for the page title.

I will add more to this comment later

murphp15 avatar Feb 15 '24 10:02 murphp15

  • [x] 1. Overview is for both SDK and Control Service
  • [x] 2. The structure is good
  • [x] 3. Getting started doesn't make sense anymore
  • [x] 4. Data sources - spam and 100s of data sources and like .. .. .. check here.
  • [x] 5. Python dependencies - part of the page about deployment
  • [x] 6. In the CS Key concepts should be - Properties and Secrets - for the Key Concepts - take it from swagger-ui - https://supercollider.vmware.com/data-jobs/swagger-ui/index.html
  • [x] 6. UI installation is just together with control service and just access
  • [x] 8. Plugins - each plugin has documentation - use each README
  • [x] 9. Root readme of plugins also is good - https://github.com/vmware/versatile-data-kit/tree/main/projects/vdk-plugins
  • [x] 10. Jupyter plugin in plugins
  • [x] 11. config help and search by prefix

zverulacis avatar Feb 15 '24 11:02 zverulacis

  • [x] 1. Getting started - remove
  • [x] 2. Dictionary - rename - glossary
  • [x] 3. Fix the Key concepts page
  • [x] 4. Overview is good - that it it combines both SDK and Control service
  • [x] 5. Document the UI installation
  • [x] 6. Sidebar - move to right + highlight the page that the person is currently on (this is impossible)

zverulacis avatar Feb 15 '24 12:02 zverulacis