I’m creating this post so when I come across something in the documentation that drives me nuts, could use improvement, is missing information, or any of the other things that I think might be useful for improving the documentation I can just add to a single post rather than create a new one resulting in further spreading out of information that is not cross-referenced. First item coming up in a second…
2 Likes
Issue: Not all information is clear or is missing CLEAR statement.
Example: The page about converting a disk image with mender-convert does not state what operating systems are known to work for the docker mender-convert environment. This is problematic for those who might use Windows full time or even part-time, as I am occasionally. The doc does not state anything about if Windows being acceptable or to build the docker-mender-convert container. Of course, one gathers, from the script used to set up the environment, that Linux is the only OS that should be used and that Ubuntu is the OS that is most likely the best one to use (since the page’s link to info on installing the docker engine happens to have ubuntu in the link’s location).
Improvement Suggested: Let the user know in the document itself, maybe just a line at an appropriate place that says please note, Windows is not supported and Ubuntu is your best bet for distribution since we created the docker-mender-convert container on an Ubuntu system
2 Likes
@rushowr Heh thats a fun coincidence! I was just giving mender-convert some spin on macOS and planned to extend the documentation in exactly the way you suggested. Incoming soon!
Thanks, and feel free to tag/DM me on topics like this.
Greetz,
Josef
2 Likes
@TheYoctoJester I’ve DM’d you, awaiting your response. The resulting conversation, as I walk you through the project and the issue I’m facing, will definitely expose quite a few of the documentation issues as well.
1 Like
Issue: Tone-deaf Documentation Contribution Invite “Sounds” Like a Challenge
Example: I believe it’s on every page, here’s the content from one of those pages.
Found errors? Think you can improve this documentation?
Simply click the Edit link at the top of the page,
and then the icon on Github to submit changes.
Note: I added the line breaks in order to just make the code block box not look quite so bad
Improvement Suggested: Change it so it doesn’t sound so “challenge-like”? That’s all I’ve got, it’s 0230 here atm.
2 Likes
Issue: Little to no explanation of the use of dd for imaging to workstation or to devices.
Granted, many users out in the professional world (myself included) know quite a bit about using dd, but what we don’t know is how Mender and dd images interact. A few alternative applications such as ddrescue wouldn’t hurt either. I used ddrescue once during my attempts to get a bootable Ubuntu 20 4 Bit image converted (never did, still waiting on any kind of useful further input there), in an attempt to have resumable imaging, due to USB transfers suddenly just stopping after a period of time.
Examples: No explanation of dd options/flags can be used and for what reason, nor any statement of which should not be used ever, etc. No alternative applications offered, which some might find useful.
Improvement suggested: dd usage and flags/options would be quite useful I’m sure, to some of your users. Also, alternative applications (ddrescue being one I tried) could be listed, obviously only if Mender’s dev team at least checks the documentation for the applications, maybe tests one or two. A simple caveat regarding alternative programs only reaching xx amount of research and/or testing could be added if necessary.
2 Likes
Suggestion: I’d like to suggest adding the current page’s last edit date.
1 Like