Standard Syntax Musings
 

Hey Jack (also sending this to the Xubuntu developer mailing list where
issues like this can be worked on together),


The click/press -syntax you are proposing sounds good.

I believe that it is okay as long as we discriminate application names
and probably button names from the text. While we might need to repeat
"dialog" and "tab" in the text, it's not too often we will need to. With
dialogs, it's usually OK as long as we tell the user to do something in
the dialog that was opened. I haven't bumped in too many "tabs" in the
documentation, but maybe we should reconsider this when we are reviewing
the syntax some time next week.


At this stage, I think it is good enough if we can discriminate all
these things under consideration from the normal text. If that's the
case, it's easy enough to give them a special style, or not.


I'm not sure about field names: how many situations is there when we
need to tell the user to fill in a specific field, not just everything
in a dialog anyway?


I would not touch the font to make something stand out of the body text.
The only exception to this is the command etc. stuff; this is because 1)
terminals use monospace fonts by default 2) the user usually needs to
copy the command exactly correctly, and a monospace font has less
ambiguous characters.


Colors... Well, we can think about it, but I wouldn't use too many
colors. The current DocBook style actually already uses a different
style for application paths, which is blueish too.


Anybody else have ideas?

Pasi

On 01/09/12 20:15, Jack Fromm wrote:

Pasi,

Re the discussion we had the other night in the chat room, I had a
couple of thoughts.


As for you question about "click" or "press" for buttons, I would
suggest that anything done with a mouse should be click and only
things done with the keyboard (e.g., Alt+F2) should use "press".


Since this help file is not going to have any screenshots, I'm
wondering if we need a way to discriminate between buttons,
application names, dialog titles, tabs and field names. It might make
things less confusing and prevent having to always specify in the text
which one of those things you are referring to. It looks like the
formatting options in the wiki are limited as to choice of fonts and
colors so if you did decide to make each of them unique, we'd have to
use a temporary format. But I would assume when you convert to Docbook
format, you would have many more options.


Or not. :-) I know it's pretty late in the game.

Jack



--
Pasi Lallinaho (knome) » http://open.knome.fi/
Leader of Shimmer Project and Xubuntu » http://shimmerproject.org/
Graphic artist, webdesigner, Ubuntu member » http://xubuntu.org/


--
xubuntu-devel mailing list
xubuntu-devel@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/xubuntu-devel

Standard Syntax Musings
 

<<I'm not sure about field names: how many situations is there when we
need to tell the user to fill in a specific field, not just everything
in a dialog anyway?>>
You may be right about that. The only section where I can remember
encountering them was Users and Groups. BTW, it looks like that section
and many others need to be edited again because apparently the latest
Quantal release has moved things around in the menu hierarchy.


Jack

On 09/01/2012 02:31 PM, Pasi Lallinaho wrote:
Hey Jack (also sending this to the Xubuntu developer mailing list
where issues like this can be worked on together),


The click/press -syntax you are proposing sounds good.

I believe that it is okay as long as we discriminate application names
and probably button names from the text. While we might need to repeat
"dialog" and "tab" in the text, it's not too often we will need to.
With dialogs, it's usually OK as long as we tell the user to do
something in the dialog that was opened. I haven't bumped in too many
"tabs" in the documentation, but maybe we should reconsider this when
we are reviewing the syntax some time next week.


At this stage, I think it is good enough if we can discriminate all
these things under consideration from the normal text. If that's the
case, it's easy enough to give them a special style, or not.


I'm not sure about field names: how many situations is there when we
need to tell the user to fill in a specific field, not just everything
in a dialog anyway?


I would not touch the font to make something stand out of the body
text. The only exception to this is the command etc. stuff; this is
because 1) terminals use monospace fonts by default 2) the user
usually needs to copy the command exactly correctly, and a monospace
font has less ambiguous characters.


Colors... Well, we can think about it, but I wouldn't use too many
colors. The current DocBook style actually already uses a different
style for application paths, which is blueish too.


Anybody else have ideas?

Pasi

On 01/09/12 20:15, Jack Fromm wrote:

Pasi,

Re the discussion we had the other night in the chat room, I had a
couple of thoughts.


As for you question about "click" or "press" for buttons, I would
suggest that anything done with a mouse should be click and only
things done with the keyboard (e.g., Alt+F2) should use "press".


Since this help file is not going to have any screenshots, I'm
wondering if we need a way to discriminate between buttons,
application names, dialog titles, tabs and field names. It might
make things less confusing and prevent having to always specify in
the text which one of those things you are referring to. It looks
like the formatting options in the wiki are limited as to choice of
fonts and colors so if you did decide to make each of them unique,
we'd have to use a temporary format. But I would assume when you
convert to Docbook format, you would have many more options.


Or not. :-) I know it's pretty late in the game.

Jack






--
xubuntu-devel mailing list
xubuntu-devel@lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/xubuntu-devel