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â forNumberField()
, and I think âmaybe thatâs something I can use forIntegerField()
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 " SeeNumberField
for parameters". So I click the link (another link!), which takes me toNumberField
. â getting worse - Under
NumberField
I still donât see explanation on âdefaultâ. So, I click another link (Ugh!!), which takes me toField
. UnderField
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.