On 10/12/2018 09:43 AM, David Malcolm wrote:
Here's a proposed "User Experience Guidelines" section for our
internals manual
It's a mixture of proposed policy, together with notes on how to
implement the recommendations.
Thoughts?
I think this documentation will be very helpful. I'll leave other
people who've worked on this aspect of the code to comment on the
content, but a few markup/copy-editing things I noticed while skimming
the patch:
- Can you please not use double-quote markup around so many words and
phrases? If there's a technical term, use @dfn{} at the first use where
you define it (and probably also an @cindex entry), and no markup on
subsequent uses. In most other cases it seemed like the quotes would
just be distracting from the flow of the text.
- I don't think "end-user" should be hyphenated when used as a noun,
although as an adjective phrase like "end-user experience" etc is fine.
- Remember to use @noindent when continuing a sentence or paragraph
broken up by a code example.
I'll take a deeper dive on the next iteration of the patch.
-Sandra
