Suggestion to improve documentations

[lamson-dev]

Suggestion to improve documentations

Description

I have a thought and want to share. More like a personal opinion. I've found it difficult to navigate through Piral documentations.

Piral Team has done an amazing job and documenting everything which makes getting started with Piral easy. Though on a day-to-day basis, I find myself needing to refer to the doc often... and struggling to find the info I need in a few clicks. (I eventually navigate to the doc I want, but not easy)

I understand you've built a brand for Piral and I believe that you'd like to maintain the Piral "look-and-feel", I wonder if you're up to trying out a different library to generate static docs site.

Docusaurus is a popular library. I'm about the bootstrap internal tech docs at my company using this lib. I hope you might find it helpful as reference.

https://v2.docusaurus.io/showcase/

Background

I had a brief discussion with @FlorianRappl on gitter. Creating an issue for tracking and involving the community.

Discussion

Florian's note:

The main issue regarding documentation layout is that we have quite some information:

• Samples
• Tutorials / Guidelines
• API reference
• Spec reference
• Plugins (and their documentation); not to mention CLI plugins, other tools and ecosystem (e.g., - Piral Inspector, upcoming VS Code Extension, GitHub action)
• Environment variables
• Comparisons and features
• Getting started
• ...

So its quite a lot and we struggle to find a great structure here that is easy to navigate and efficient. Maybe if we could collect say 3-4 layout options (1 could be similar the current one, just refined) incl. either just a mock or a sample from, e.g., using something like docusaurus (could also be something else read the docs etc. - the layout is the important part here) that would be fantastic. Once we have these options (we could also make an issue on GitHub to work on these options and have an open discussion) we can use GitHub + the chat here + Twitter etc. to link to a poll using, e.g., https://www.strawpoll.me/

[FlorianRappl]

As noted I think we should split the technical implementation from the UX. What should be discussed here is the UX, which should be improved.

Ideally, we come up with 3-4 layout options, which can be dropped in via mocks or some real world examples. Then we can have a poll to see what the users favor.

[FlorianRappl]

Option 1

Essentially like we have currently - just a bit streamlined.

Uses:

• Main navigation (more critical items) on top
• Table of content on the left side
• Tabs if needed (sub items)
• Search via main nav bullet item

Example: https://docs.piral.io/reference/documentation

Option 2

A refined "grand-scale" information central.

Uses:

• Main navigation (more critical items) on top
• Table of content on the left side
• Breadcrumbs if needed (sub items)
• Search via main nav bullet item

Example: https://www.wolframphysics.org/technical-introduction/

Option 3

Provide an established look with 3 columns.

Uses:

• Main navigation (only most critical items) on top
• Table of content on the right side
• Specific navigation (sub items) on the left side (collapsable)
• Search via direct input box

Example: https://docusaurus.io/docs/en/installation

Option 4

Simplified with an adjustable nav element.

Uses:

• All navigation (incl. sub items) on the left side (changes, collapsable)
• Table of content is in the navigation on the left side
• Bread crumbs available, too
• Search via direct input box

Example: https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html

More?

Any more options that you'd like to discuss? Just ping me or add a reply. I'll integrate it in here.

[lamson-dev]

Another option following examples:

https://reactjs.org/docs/getting-started.html and https://graphql.org/learn/

Uses:

• Main navigation (more critical items) on top
• Table of content on the right side
• Search via direct input box

https://www.howtographql.com/

Uses:

• Dedicated for tutorials
• Different tutorial for different combinations of frameworks
• Search tutorial based on framework via direct input box
• Progress tracking supported

---

I'll vote for Option 3 because:

• 3-columns layout is great for discoverability. It makes good use of screen real estate (screens are getting wider nowadays). We can still see the main content in center of the screen and have navigations on both side.
• Search is available
• Familiar with other Docs. From my experience, I've seen more than half of the frameworks I work with having this layout for Docs - including https://create-react-app.dev. When I switch between docs, I have no problem navigating because they're familiar.

[lschoett]

Another option, which is a mixture of the options above:

• Main category navigation on top, e.g. "Documentation", "Samples", "Tutorials", "Reference"
• Table of content with sub levels on the left hand side
• Search the docs with a dedicated input box on top of the left navigation

Examples:

• https://docs.docker.com
• https://kubernetes.io/docs/concepts

[SantoJambit]

Just an idea (haven't read through the suggestions in detail yet, will do later):

I've recently come accross vuepress, which I now use for some of my projects together with github-pages-action for automatic deployment into the gh-pages branch. I think it creates quite beautiful documentation.

Seems quite similar to the create-react-app documentation.

[FlorianRappl]

I've recently come accross vuepress

So this would be option 3 then I guess. Pretty much the "docusaurus" design.

[SantoJambit]

@FlorianRappl Option 3 has a TOC on the right side. With VuePress, the left side is both navigation and TOC. Unless I misunderstand this, it looks more like Option 4 from a UX perspective, though I don't like the sample for Option 4, because there's little overview in the left navigation. So maybe Option 3.5?

Option 3 would be fine too though.

What I don't like about the current Piral documentation are these huge pages with a huge TOC. I'd rather have smaller (sub-)pages which focus on one thing. Otherwise it feels quite overwhelming.

@lschoett looking at the kubernetes docs, there seems to be no TOC at all, just a sub-navigation on the left side. To be clear, what I define as TOC here are the headings of one page. I like having a TOC, so I'd vote against that option.

[FlorianRappl]

Yeah I agree with 3.5, but note that the TOC on the RHS is just in case when there are other headlines, too. In the end we'll need to see about these things.

Regarding:

What I don't like about the current Piral documentation are these huge pages with a huge TOC. I'd rather have smaller (sub-)pages which focus on one thing. Otherwise it feels quite overwhelming.

Does that apply to the tutorials or the reference pages @SantoJambit ? For the latter we definitely need to / want to have this revamp, for the former I'm not sure if we can strip them down more.

[lschoett]

@SantoJambit The example for the Kubernetes docs was just a layout suggestion. As the documentation content for Kubernetes is rather large, they have placed the detailed TOC entries within the pages.

I think it is important to have the entire navigation structure (at least level one) visible at all time, so users can navigate through the entire content. On option would be to collapse the navigation for all first level navigation items and only show the detailed structure in context with the currently "open" page.

[SantoJambit]

Talking about the reference pages. The tutorials should be fine I think.

[carvinlo]

Perhaps in the parallel development of multiple projects, the environment configuration guide for development and debugging is more important. Perhaps it is easier to find Tooling in the tutorial than in the faq. Then perfect the configuration steps and summarize some useful tools, such as sample-pilet-service.

[FlorianRappl]

Two documentations for reference:

• https://squidfunk.github.io/mkdocs-material/releases/5/
• https://kyma-project.io/docs/components/application-connector/

There are many things I really like about the former. The great thing about the latter is that the RHS (current jump points / TOC) are always in the current level. Therefore, the list remains always quite compact and is nicely visualized.

[SantoJambit]

I don't like the latter:

• it is a huge page and you notice that it gets sluggish when scrolling.
• when scrolling, the TOC gets modified and this is quite distracting, at least to me.

About the former: I think I like the graying out of the TOC for tutorial-style pages, since you see your progress, but I'm not sure if this is nice for reference pages.

[FlorianRappl]

Alright - besides the actual UX flow I'd bring in new Markdown capabilities that we will actively use.

We will support (info) boxes:

!!! tip "Tip Header"

    Body ...

!!! warning "This is a warning title"

    Body ...

!!! failure "Error: Title"

    Body ...

We will also support tabs:

=== "Unix"

...source code on -nix systems
```

=== "Windows"

```

...source code on Windows systems

We will also support collapsed views:

??? summary "Summary title"

    Body ...

Every code snippet will be easy to copy to the clipboard, too.

[FlorianRappl]

Quick summary what changes we will do:

• [x] Refine the layout, similar to MkDocs, for details see below, (1)
• [x] Update our Markdown use with fences for rendering info boxes, tabs, and collapsed views
• [x] Restructure the documentation, see (2)
• [ ] Provide some new documentation on missing (advanced features), see (3)

Regarding (1):

• New top-level navigation items
• Structure display of current top-level navigation item on the LHS
• Table of contents of the current page on the RHS
• Search input directly visible
• Sticky top navigation bar
• Clicking on a top-nav item leads directly to the first content page instead of an overview
• Next and previous will always be available
• The homepage will be the first article
• The FAQ will move to the footer

Regarding (2):

• Top-level navigation items:
  • Guidelines (like right now)
  • Reference (contains a collection of articles, not a wild list; articles such as "Browser Support", "Alternatives", "Features", "History", "Error Handling", "Articles", but also the available specifications such as "Piral CLI Specification" or "Piral Feed Service Specification" etc.
  • Plugins (contains the list of Piral plugins)
  • Tooling (contains reference on the Piral CLI, its commands, available plugins, as well as documents for "Piral Inspector", "Piral VS Code Extension", and the utility packages (SSR Utils and Jest Utils)
  • Types (contains the type reference for piral-base, piral-core, and piral)
  • Examples (contains the samples page, as well as links to the piral-samples GitHub orga and other available examples)

Regarding (3):

• New guidelines
  • Extending Pilet loading, e.g., for using SystemJS with top-level importmaps
  • Using a different bundler,e.g., Webpack
• New content
  • Piral Inspector
  • Available usage / development paths

[Robbson]

I haven't read all the comments above but I always have difficulties finding the right information in the existing Piral docs. It also happened that I missed some pages completely even though I had a look in the related sections several times before. Like the tabs on the reference page where you can switch between introduction and reference.

Main reasons

• Lack of contrast: All navigation menus/indices are hard to read, probably optimized to look great on Retina displays but hard to read anywhere else
• Lack of contrast II: even the main text is not black but a dark gray which affects contrast, too
• Structure: The guideline's chapters and their child sections should be accessible in one index
• FAQ has no index at all
• search bar has no full text search

Alternative

I've found an alternative: Open the folder containing all the markdown docs in Typora enables a much better experience than access the docs on the web. Crisp clear output, full text search, at least navigation by file & index.

[burakakca]

My opinion : Option 3

I did not read all the comments, but I want to share something that I think is related to this discussion.

Are the codes in the directive documentation added only to give an idea, or have they been added to complete an incremental step by step? also, to be quick, see the example on github might be good

[FlorianRappl]

This will ship in 0.11.8 - the remaining bullet point

Provide some new documentation on missing (advanced features), see (3)

will be provided on the road to v1.