[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [platform-doc-dev] documentation style guide
|
Argh, Notes! -- Really, it looked good on my machine,
Here are my comments reformatted:
- Is the comment "...display the name in a bold font. There are
different ways this can be done:..." for expediency or is this
actually what we are advocating? That is, if the <span> based
version is the best strategy, shouldn't we just tell people to
use it?
- Re: " instruct the user to "right-click". This has the well
known problems:
1) mouse buttons are reversed for left handers.
2) Mac users may have only single button mice.
Have we decided to ignore this? [Note: I'm ok with that, I
just want to make sure that this is not an oversight.]
- It's odd that we "click" push buttons and radio buttons, but
"select" check box buttons. It's not clear that there is a
better answer, however.
- Re: "Do not instruct the user to "click on". Use "click the
<name of tab>." | Click the General tab." Aside from seeming
like a duplicate of the previous style point, the example does
not match the instructions. That is, the name of the tab is
"General", so to follow the instructions as written you should
say "Click the General."
- Traditionally, related concepts were relegated to their own
section in each page. Because of the comment "Consider having
inline links to concepts that are Eclipse-specific." I assume
we have decided to not do this. Should the separate section be
removed (or only included if a particular related concept is
not mentioned in an inline link)?
- Since most tools add generator tags, does "Remove all generator
tags and author tags." mean that we should actively go and
remove them (each time?) after editing? If this is important,
can it not be post-processed rel. eng. or the help team?
hoping that's more readable,
McQ.
Mike Wilson/Ottawa/IBM@IBMCA
Sent by: platform-doc-dev-admin@xxxxxxxxxxx
12/08/04 13:24
Please respond to
platform-doc-dev@xxxxxxxxxxx
To
platform-doc-dev@xxxxxxxxxxx
cc
Subject
Re: [platform-doc-dev] documentation style guide
Random comments from someone who has not been tracking this closely:
Is the comment "...display the name in a bold font. There are different
ways this can be done:..." for expediency or is this actually what we are
advocating? That is, if the <span> based version is the best strategy,
shouldn't we just tell people to use it?
Re: " instruct the user to "right-click". This has the well known
problems:
mouse buttons are reversed for left handers.
Mac users may have only single button mice.
Have we decided to ignore this? [Note: I'm ok with that, I just want to
make sure that this is not an oversight.]
It's odd that we "click" push buttons and radio buttons, but "select"
check box buttons. It's not clear that there is a better answer, however.
Re: "Do not instruct the user to "click on". Use "click the <name of tab
>." | Click the General tab." Aside from seeming like a duplicate of the
previous style point, the example does not match the instructions. That
is, the name of the tab is "General", so to follow the instructions as
written you should say "Click the General."
Traditionally, related concepts were relegated to their own section in
each page. Because of the comment "Consider having inline links to
concepts that are Eclipse-specific." I assume we have decided to not do
this. Should the separate section be removed (or only included if a
particular related concept is not mentioned in an inline link)?
Since most tools add generator tags, does "Remove all generator tags and
author tags." mean that we should actively go and remove them (each time?)
after editing? If this is important, can it not be post-processed rel.
eng. or the help team?
McQ.
_______________________________________________
platform-doc-dev mailing list
platform-doc-dev@xxxxxxxxxxx
http://dev.eclipse.org/mailman/listinfo/platform-doc-dev
