[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
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.