• Browse GIT
• View
• Edit
• Upload
• History
• Print

TheLyXDocStyleSheet

The LyXDoc StyleSheet — The general style of the content of the documentation. (As opposed to typgraphic and notational conventions).

1.  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:

1.1  NEVER NEVER NEVER EVER Treat the Reader as if She is Stupid

1. No dumbing-down.
2. No talking down to the reader.
3. The reader is smart enough to know what a mouse is.
4. The reader is smart enough to know how to use a keyboard, including the Shift-, Control-, and 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.)
5. 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 content.)
6. 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.

1.2  Write as if You're Talking with a Friend

1. Think that way when you write. Play the dialogue in your mind.
2. Be as informal as you please (without being rude).

1.3  AVOID the Passive Voice

1. 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 ..."
2. 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."
3. Rule of thumb: any sentence you can express as, "It was done by foo," you can express as, "Foo did it." Much nicer.
4. 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.
5. DO NOT use the passive voice. It's awkward and hard to read.
   Note to non-Americans:
   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, often unnecessarily.

1.4  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 paragraph.

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 literary prize.

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