code consistency

Gunnar Hjalmarsson gunnarhj at ubuntu.com
Sat Feb 28 14:26:43 UTC 2015


On 2015-02-28 11:52, Hannie Dumoleyn wrote:
> In unity-introduction.page I see the word The Dash in 3 different
> ways:
> The <gui>Dash</gui>
> The <em>Dash</em>
> the Dash
> Does it look better if only one formatting code is used. One may
> argue that it depends on the context. Since I am doing this
> proofreading for the first time, I want to know what the policy of
> the docs-team is.

http://bazaar.launchpad.net/~ubuntu-core-doc/ubuntu-docs/trunk/view/head:/ubuntu-help/C/unity-introduction.page

As regards <gui></gui> vs. <em></em>, the former is intended for strings
in GUI components.

http://projectmallard.org/1.0/mal_inline

Since there is no visible "Dash" string in the GUI (it's just the name
of the feature), I would say that we should use "the <em>Dash</em>", and
not "the <gui>Dash</gui>".

Ok, so if we emphasize a word using <em></em>, should we do so
consistently? I'm not aware of any team policy in this respect.
Personally, in this case, since it's a name of an important feature, I
feel that consistently using "the <em>Dash</em>" is appropriate. OTOH I
can think of situations when you emphasize a word using <em></em> only
once, and where it would be 'too much' to do so throughout the page.

> Am I too picky, or should we be more consistent?

You are certainly not too picky. ;)

-- 
Gunnar Hjalmarsson
https://launchpad.net/~gunnarhj



More information about the ubuntu-doc mailing list