Improve documentation delivery to users - analysis

[tomekpapiernik]

What could be done to improve the way we deliver documentation to users?
Put together a list of ideas and known drawbacks of our current setup.

[tomekpapiernik]

1. The documentation is available to the users in 3 separate locations:

• GitHub
• kyma-project.io website
• cluster UI
  This creates unnecessary confusion where it comes to deciding which source is the most up-to-date and the ultimate source of truth.

Proposed solution: Stop rendering documentation in the cluster UI. Redirect from cluster UI to kyma-project.io. Treat GitHub as a source only. Direct all traffic to the website.

2. Linking from one document to another is not available. This hampers the UX severely and has been reported as a hindrance by POs.

3. The styling used on the website makes it hard to read.

• The font size of the main content area is too big.
• Scrolling through the content is not reflected in the navigation panel. Currently, active topic should be highlighted.
• Heading sizes are confusing. There is very little to no difference in size and style between a heading that introduces a new topic, and a H2 heading used to introduce a new section in a document.

4. The website allows the user to see only the documentation for releases and ignores changes to the master branch completely. Additionally, the newest release is dubbed "latest" which might introduce confusion ("latest", as in the latest tag, which is not the same as the release).

Proposed solution: Add a "latest" version to the menu and allow it to be updated at any point in time so that the website represents the master branch documentation state accurately. Don't call releases "latest" anymore.

5. Adding a "search" option would improve the user experience greatly. We do have a lot of nice and detailed documents, but it might be difficult to know exactly where to look just by scanning the topics in the left-hand navigation.

[kazydek]

One from me: Images are extended to cover the full width of the page which sometimes results in them being unproportionally big. See this example.

[derberg]

Thanks for the feedback, next time better granular it a bit more in separate tickets and also check if some of them are not already addressed in the backlog ;)

1. Current strategy is that:

• all docs for all versions are in kyma-project.io/docs at this website is an entry point for community to kick of with Kyma
• cluster docs are for actual Kyma users that already work with Kyma. Long term we want to have most of the docs-ui visible in the context of each view to make experience even better. So far we got feedback from Kyma users that worked on a cluster that they like the approach that they have docs for their cluster version always there, they do not have to leave console UI. No plans to change this strategy but of course I'm opened for discussion, especially if you have some feedback from current Kyma users that feel confused about it.
• github is treated as source and this is why we do not link to docs in github from https://github.com/kyma-project/kyma or for example when you see release notes, they always link to kyma-project.io/docs. If it is not that obsious please make a pull request to enhance description here https://github.com/kyma-project/kyma/tree/master/docs to make it more clear

2. We already have a ticket for that Enable linking between documents website#103
3. Please create ticket in website repo, this has to be consult first with designers
4. We already have a ticket for that Render more than just docs for official releases website#126
5. We already have an epic for that Set up a chat bot  website#106
6. Regarding images. Please create a ticket in website repo, we need to think about it, that is not so straight forward and different solutions must be considered.

[klaudiagrz]

After a short discussion with the devs, we figured out that adding the "Copy" button to the command fields would be really convenient. Have you ever considered adding such an option? See the example:
https://cloud.google.com/iam/docs/creating-managing-service-accounts#listing_service_accounts

[derberg]

Sure. Don’t ask, just create an issue ;) We had this in previous project we worked on and know devs love it. Of course that won’t be implemented over night, we need to discuss details and get design and icons but anyway don’t be shy ;)

[kazydek]

I created kyma-project/website#133 for the image size issue.

[klaudiagrz]

I've created an issue for the "Copy" button:
kyma-project/website#132

[derberg]

@klaudiagrz but ugly one that doesn't follow the template 😛

[klaudiagrz]

@derberg Sorry, next time I'll pay more attention to it 😉
I've already improved this issue.

[tomekpapiernik]

@derberg
Thank you for linking all of the issues related to the problems and doubts described in this issue.
I created an issue for improving the website styling:

kyma-project/website#137