[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [platform-doc-dev] documentation style guide
|
Mike Wilson wrote:
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?
It's a bit of a trade-off:
The appeal of <span class="name"> is that you can display GUI labels,
GUI buttons, and so on in a way that matches your corporate standards.
The problems with <span...> are that this requires the reworking of
pretty much every help topic and the CSS file, and it is slightly more
difficult to use (<span class="guilabel"> being more complex than <b>).
I believe that the flexibility of the <span...> technique justify the
effort, but this does require general agreement from the Eclipse
documentation community.
Re: " instruct the user to "right-click". This has the well known
problems:
mouse buttons are reversed for left handers.
On the Windows mouse-configuration dialog you can set the Left Mouse
button to "Right-click". Thus "right-click" means "perform the
right-click operation", but it does not necessarily mean "click the
right-mouse button". Confusing for users, but a godsend for technical
writers.
Mac users may have only single button mice.
Good point. Perhaps right-click mouse operations need to be added to the
CSS chart:
"Right-click" mouse operations for Macs can be put into
<p class="carbon"> tags.
We need a new category (CSS > Mouse Operation > notmac) for
right-click mouse operations for platforms other than Macs.
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."
Good catch: the instructions should be:
...Use "click the <name of tab> tab."
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.
I suggest retaining the "Related..." sections, which are very useful,
and adding links to appropriate concepts in the body of the topic as
well (which is what you would normally see in a hypertext document).
These extra links may seem to be redundant, but take for example the
Workbench User Guide > Reference > Preferences > Workbench topic, where
you will see:
Workbench
---------
The term "Workbench" refers to the desktop development environment.
...
I'm proposing that "Workbench", which is in italics to indicate that it
is an Eclipse-specific term, should also be made into a link to the
Workbench User Guide > Concepts > Workbench page. It happens that there
is no "Related concepts" section in this topic for that link, which is
an oversight. However, even it a "Related concepts" section were there,
it would be a page-down or two before the user would see it. It is much
more useful to have the link at the point of introduction of the new
terminology.
The reason that you also keep the "Related concepts" section is that
there may be concepts that are not mentioned explicitly in the body of
the topic that are still reasonable for the user to explore. (And if
there is no explicit mention, there is no place to apply the link in the
body of the topic.)
Should the separate section be removed (or only included if a
particular related concept is not mentioned in an inline link)?
We should have both.
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?
The author tags appear on the front page of PDFs we (Red Hat) produce,
so we definitely have to remove these tags before we can use the files.
It turns out that we produce PDFs only from "Getting Started" tutorials,
so from our point of view, only these files need to be cleaned.
The request that generator tags be removed is less important to us, but
these are something that we remove as we come across them. I'm mainly
looking for confirmation that if we provide eclipse.org with a topic
that has been improved in some way (say, to fix a typo), that no one
minds if we remove a generator tag that happens to be in that topic.
Mike Behm
Red Hat Canada Ltd.
