<< | Page list | >>
The LyXDoc StyleSheet — The general style of the content of the documentation. (As opposed to typgraphic and notational conventions).
The LyXDoc StyleSheet
The LyXDoc StyleSheet — The general style of the content of the
documentation. (As opposed to typgraphic and notational conventions).
When contributing to the primary — i.e. the English language version
— of the LyX documentation, keep the following in mind:
NEVER NEVER NEVER EVER Treat the Reader as if She is Stupid
- No dumbing-down.
- No talking down to the reader.
- The reader is smart enough to know what a mouse is.
- The reader is smart enough to know how to use a keyboard, including the
Meta- keys. (The introduction of most of
the manuals takes care of the "
Meta- is the
Alt- key" issue, so
you don't need to.)
- The reader is smart enough to know that "at the cursor" means "where the
text cursor is sitting right now, in the buffer currently visible."
(Anything more than the word "cursor" is, IMO, superfluous and wll be
deleted . So, save yourself the typing, save the editor the cutting, and
save the reader the strain of sifting through extra verbage that adds no
- Rule of thumb: the reader is not an imbecile. The reader is merely lost;
point them in the right direction, and they can take it from there.
Write as if You're Talking with a Friend
- Think that way when you write. Play the dialogue in your mind.
- Be as informal as you please (without being rude).
AVOID the Passive Voice
- No: "It is felt that this name best explains the command's purpose." We
know full well who wrote the command: "The LyX Team felt ..." Or, better
yet, "We felt that ..."
- Things don't happen by magic - somebody or something did it. Only
politicians use the passive voice to cover up who did something. If LyX
reformats a paragraph, write, "LyX reformatted the paragraph." If ispell
makes changes, write, "ispell changes the document."
- Rule of thumb: any sentence you can express as, "It was done by foo," you
can express as, "Foo did it." Much nicer.
- I know it's tough. We all hear way, way too much garbage English on the TV
every day in the passive voice. Some people think it makes speech
better. It doesn't. It makes speech baroque, if not outright
byzantine. With a little effort, you can wean yourself off it.
- DO NOT use the passive voice. It's awkward and hard to read.
Using passive voice is generally considered bad style in the U. S. as it
is too easy to obfuscate your words with it. It also bloats sentences,
Short Sentences. Short Paragraphs.
In English, there is a grammatical error known as the "run-on sentence." The
classic example of a run-on sentence is 7 clauses strung together with the
word "and." There are, however, less obvious run-on sentences, ones using
too many subordinate clauses. Such sentences may look elegant because they
are complex. However, they are also extremely difficult to read because they
are so complex.
In general, stick to short sentences in written English. Getting rid of
passive voice ("...was done by...") shortens and simplifies them. Hacking
apart sentences with many dependent clauses is another way to shorten
sentences. There are ways to do this yet still have a smooth-flowing
While I'm talking about paragraphs, I'll apply the "shorter is better" motto
to them, as well. At the time I started with the manuals (and this Style
Sheet), I didn't pay too much attention to paragraph size. I've since become
a big proponent of short paragraphs, with one idea per paragraph. While
long, flowing, multi-concept paragraphs can be nice in novels, we're writing
manuals. Our goal is rapid information location and comprehension, not a
There is a single exception to the short sentence, short paragraph
rule. Particularly complex ideas may need more "breathing room." However,
you shouldn't encounter such complex ideas often when documenting LyX. Try
to keep things short, and use your judgement as needed.
- When in doubt, compromise.
- When in doubt, use good judgement.
Hopefully, you've got the idea (grin).
Category: Development, Documentation, Documentation development