degville
commented
1 month ago Hi @PhilStollery. Thanks so much for this, and sorry for the delay responding. I'll take a look at your PR, but to answer your excellent questions first:
When highlighting interface elements on screenshots — is there a standard colour or shape (round rect - Ubuntu orange is what I used)?
We don't have a standard because our standard approach is usually to try and avoid screenshots, for a few important reasons. They're difficult to maintain, and GUI elements often change, quickly making screenshots out of date. They're also difficult to find through a documentation search, especially if you're looking for a description. There are accessibility issues too, perhaps for people who can't use a normal display, and they're difficult to fit into translated documentation.
This page is one of our few examples, though, because sometimes you do indeed need to show what you're writing about. What you've done looks good.
Does Canonical like to reference the readers as YOU or include them with WE?
Good question! You can probably find examples of both in our docs, but we do have a strong preference for you.
Is there a preferred code referencing style for parameters to code (I used )?
No, but we absolutely should! This might actually be a great challenge for the Academy.
I saw conflicting Markdown and HTML for headers — I made all of them Markdown.
Thanks! You did the right thing. The reason for the HTML headers is to make-up for a limitation in Discourse documentation.
PhilStollery
Fixes #8
This is my first PR into the Open Documentation Academy. I've read the Canonical style guide but I still have some style questions:
My aim for this PR was removing doing content into the How To document. The explanation is now maybe a bit too simple? Should I expand on it?