A user-experience thread.
The first image is of the first code on the page.
The second has the last code on the page.
Both are from the @chocolateynuget documentation docs.chocolatey.org/en-us/choco/co…
I totally missed that the second one has more than 23 lines.
1/
The first image is of the first code on the page.
The second has the last code on the page.
Both are from the @chocolateynuget documentation docs.chocolatey.org/en-us/choco/co…
I totally missed that the second one has more than 23 lines.
1/
There are two reasons for this:
1. The last bit of code shows default options and switches like --help, --debug and --verbos, is under a ind of caption pointing to an article about those and followed by a kind of caption about specific options for the "choco install" command
2/
1. The last bit of code shows default options and switches like --help, --debug and --verbos, is under a ind of caption pointing to an article about those and followed by a kind of caption about specific options for the "choco install" command
2/
2. The last bit of code ends exactly at a code line.
3. The light-blue lines look unlike any normal scrollbar on my system and in my browser (in a trimmed down browser like @archiveis uses, they do look like regular scrollbars: archive.ph/2022.09.16-194…).
3/
3. The light-blue lines look unlike any normal scrollbar on my system and in my browser (in a trimmed down browser like @archiveis uses, they do look like regular scrollbars: archive.ph/2022.09.16-194…).
3/
@archiveis Here the "form over function" user experience totally put me on the wrong foot and actually made me save the "choco install --help" output to a @github gist to be readable: gist.github.com/jpluimers/6ee0…
4/
4/
@archiveis @github Having that help output be scrollable is kind of useless as it is the most important documentation on the page (and a few bits of it would make up for a paragraph of explaining documentation by itself), especially for non-regulars that want to help out updating a package
5/
5/
and want to figure out what the "-dv -s ." abracadabra of "choco install packageName -dv -s ." means at community.chocolatey.org/courses/creati…
Note: it means "--debug --verbose --source=." and should have been an example before the others to help novice users get going.
6/
Note: it means "--debug --verbose --source=." and should have been an example before the others to help novice users get going.
6/
Documentation should put clarity over brevity and novice or occasional users over expert users.
That way you are more welcoming the (much larger!) first groups of users and show you have an eye for #inclusion and #a11y (accessibility).
7/7
That way you are more welcoming the (much larger!) first groups of users and show you have an eye for #inclusion and #a11y (accessibility).
7/7
• • •
Missing some Tweet in this thread? You can try to
force a refresh
