Improve README from onboarding notes #4247
Conversation
…d some helpful extra commands to the README
viambot
added
the
safe to build
✅ Deploy Preview for viam-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
|
||
| ```sh | ||
| make serve-dev-draft | ||
| ```console |
There was a problem hiding this comment.
[q] Why change all of these?
There was a problem hiding this comment.
Think of it kind of like our command-line styling in the docs, where we include a prompt character ($) to indicate an interactive snippet, but a full shell script (even a one-liner) doesn't include the prompt. It's a subtle piece of UX, and currently the GitHub markdown preview doesn't do anything special with it, but technically it could someday. And in the meantime, it's very very very slightly better for folks with screen readers, so I try to follow the convention when possible (and spread the word, now you've hopefully been infected by the console mind-virus).
| To check locally for broken links, install [`htmltest`](https://github.com/wjdp/htmltest): | ||
|
|
||
| ```console | ||
| brew install htmltest |
There was a problem hiding this comment.
Nice! However, [opt] could mention this is for mac and/or point non-mac users in the right direction. Majority of employees are using macs but external contributors and a handful of Viam folks have other machines.
There was a problem hiding this comment.
Very very true. However, most of the rest of the docs don't cater to non-macOS users, and honestly when I used Linux for work I ironically found the brew formula registry (https://formulae.brew.sh/formula/htmltest in this case) one of the best ways to find install steps for Linux, because the pages are short, simple, and always link to the source code and project homepage.
Backlog addition: add info for Linux users throughout the README. I just wish GFM (github-flavored markdown) would add support for tabs, because lining up installation instructions for each platform sequentially is kind of a pain.
There was a problem hiding this comment.
Interesting. Yeah this readme doesn't have to cater to Linux now, but I'm surprised you say the docs in general don't--most machines run on Linux (e.g. Pi)! Have you noticed specific places where we abandon Linux users?
Co-authored-by: Jessamy Taylor <75634662+JessamyT@users.noreply.github.com>
Fixes some broken links, broken commands, spruces up appearances, and adds some helpful extra commands and section titles to the README.