Better documentation

💡 Feature Requests
1

Clearer documentation pages

Hi! Sometimes I found it hard to navigate in the documentation pages.

Relevance: I think it’s mostly relevant to new starters with Viktor platform, and non-first-time users who need to check basic things from time to time.

Proposed design

1. Visualisation of what a code section does

To provide visually an idea of what the user is going to get, and help the user to locate relevant code sections more quickly.

Take numeric-input page as example. There are subtitles, which helps, but it is in my opinion still somewhat text- and code-rich. For a beginner in coding it may help a lot to see a screenshot of “what will I get if I use this code section”, next to (or above or below) each code sections.

May be even better if that can be interactive, like dash-bootstrap-components - input.

2. A list of all available arguments, within the same page (perhaps at the end of the page)

Sometimes the user need to navigate a lot to find what they need, especially for someone who is new to the documentation. I found my patience and faith wearing down as I navigated among different sections in a page, or different pages, or each time when there is a “maybe they mean this…?” moment. That feels quite unfriendly to me. I wonder if there is anything that we can do to create a smoother experience.

Take again numeric-input page as example. Say I want to make a slider with integer inputs, with 750 - 1000 as range and 850 as default. With unfamiliarity on how the doc is organised (and with my impatience), this is what happens:

  • First, I find a subtitle “Integer” in the page, and directly see IntegerField(). → that’s great
  • I see no example arguments for IntegerField(). Then, under another subtitle, I see “setting min/max” for NumberField(), and I think “maybe that’s something I can use for IntegerField() too” → not super, but good enough till this point
  • I still need to know how to set default value for my slider. Like what I did with the max/min, I try to find that info under other sections in the page, but don’t find it. After 1 minute I see I need to click “IntegerField”, which takes me to another page IntegerField. → getting slightly impatient
  • In this new page, I see an argument ‘default’ for IntegerField(), but no sure what’s what I need because there is not explanation. Then I see " See NumberField for parameters". So I click the link (another link!), which takes me to NumberField. → getting worse
  • Under NumberField I still don’t see explanation on ‘default’. So, I click another link (Ugh!!), which takes me to Field. Under Field I finally find what I need.

New edits below

3. Easier way(s) to give feedbacks on documentation

At the end of each page in the documentation the users can up- and downvote under “Was this page helpful?”, but no further comments can be submitted. For now they have to come to the community forum to give feedbacks (as “feature requests”, I assume?).

Maybe show a textbox after a user clicks up- or downvote, which they can use to submit small and page-specific feedbacks?

4. (A rather small point) in “Getting started” pages there are some Youtube videos which cannot be viewed full-screen

Watching them within the documentation page seems impractical (because everything in the videos is too small to make out). A slight inconvenience to me. A workaround is to click “watch in Youtube” and watch them in another tab.

2

Thanks for such an elaborate write-up and especially the concrete proposals of how to improve! We will definately take this to heart and try to improve.

it may help a lot to see a screenshot of “what will I get if I use this code section ”

Trying to understand what would be ideal here. In other parts of the docs we have more visual elements, for instance in the guide on data visualizations: Results & visualizations - Data & tables | VIKTOR Documentation. is this a bit the direction that you meant?

3

Ah yes that’s what I meant!

After looking at the example page you send, another point: I personally find those texts in the screenshots too small to read without paying extra effort. To see what’s in a screenshot, I need to pauze to look at it harder, or to click to zoom in; both actions interrupt an otherwise smooth reading/scanning expereince for me. Would be very nice to have screenshots with similar height and width but larger fonts.

1 Like
4

Hi @amy.jxz

Thank you for writing up these elaborate improvement points.

With respect to:

  1. Easier way(s) to give feedbacks on documentation

At the end of each page in the documentation the users can up- and downvote under “Was this page helpful?”, but no further comments can be submitted. For now they have to come to the community forum to give feedbacks (as “feature requests”, I assume?).

Maybe show a textbox after a user clicks up- or downvote, which they can use to submit small and page-specific feedbacks?

We have just released a new version of the docs where you can provide additional information!

image
image910×488 22.1 KB

1 Like
5

Hi @amy.jxz

We have received some more feedback on the input fields pages you refer to, and tried to make some improvements. For now we applied these to the following pages only:

with the idea to keep the pages clean, giving a quick overview of what the field will look like, and an additional collapsible section to see all available arguments. We could even add figures to each example in the collapsible if it helps.

Could you perhaps take a look at this and share your thoughts?

6

Hi @amy.jxz

Friendly reminder, were you able to check out the updated docs I mentioned above?