#This file was created by <lasgoutt> Thu Jan 22 16:01:53 1998
#LyX 0.12 (C) 1995-1998 Matthias Ettrich and the LyX Team
\lyxformat 2.15
\textclass article
\language default
\inputencoding latin1
\fontscheme default
\graphics dvips
\paperfontsize 12
\spacing single 
\papersize letterpaper
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 1
\papercolumns 1
\papersides 1
\paperpagestyle plain

\layout Title

Documentation Project Style Sheet
\layout Author

by John Weiss
\layout Abstract

This article is a style sheet.
 It describes, with examples, how the documentation should look and sound.
 It also explains the purpose of each of the different manuals.
\layout Section

Fonts
\layout Standard

Since this is the easiest section, I'll start here.
\layout Standard

This is how you should fontify text in the manuals:
\layout List
\labelwidthstring MMMMMMMM


\emph on 
Emphasized
\emph default 
 general emphasis, generic arguments, titles of books, names the other manuals
 and of their sections, and notes from the authors
\layout List
\labelwidthstring MMMMMMMM


\family typewriter 
Typewriter
\family default 
 program and file names, LaTeX code, LaTeX commands, LaTeX package names,
 and LyX code and functions
\layout List
\labelwidthstring MMMMMMMM


\family sans 
Sans
\protected_separator 
Serif
\family default 
 menu, button, or popup names, the names/lables of all widgets in a popup,
 the names of keyboard keys, and certain 
\begin_inset Quotes eld
\end_inset 

special terms
\begin_inset Quotes erd
\end_inset 


\layout List
\labelwidthstring MMMMMMMM


\noun on 
Noun
\protected_separator 
Style
\noun default 
 people's names
\layout List
\labelwidthstring MMMMMMMM


\family sans 
\bar under 
U
\bar default 
nderlined
\protected_separator 
Sans
\protected_separator 
Serif
\family default 
 Rich Fields added this to mimick the underlining of letters in the menus
 and on buttons.
 It helps to highlight the accelerator keys, and human brains store information
 best when they see it frequently.
\begin_deeper 
\layout Description


\bar under 
WARNING!
\bar default 
 --- When you do this, make sure you 
\emph on 
only
\emph default 
 shut off the underlining.
 Too many people send in things that look like: 
\newline 

\family sans 
\bar under 
T
\family default 
\bar default 
his 
\newline 
\SpecialChar \ldots{}
i.
\protected_separator 
e.
\protected_separator 
they not only shut off underlining, they turned off sans-serif, too! 
\emph on 
Don't do that!
\emph default 
 Make sure the entire word is still in 
\family sans 
Sans-Serif
\family default 
 after you shut off the underlining.
\end_deeper 
\layout Standard

Here are some examples:
\layout Enumerate

The function 
\family typewriter 
math-mode
\family default 
 appears in configuration files and in the LyX source.
 Therefore, it [and all other LyX function names] count as code and is set
 in 
\family typewriter 
Typewriter
\family default 
.
\layout Enumerate

However, 
\family sans 
\bar under 
M
\bar default 
ath
\protected_separator 
mode
\family default 
 is a menu item in the 
\family sans 
\bar under 
M
\bar default 
ath
\family default 
 menu, so it appears in 
\family sans 
Sans
\protected_separator 
Serif
\family default 
.
 Notice the use of 
\family sans 
\bar under 
U
\bar default 
nderlined
\protected_separator 
Sans
\protected_separator 
Serif
\family default 
 for the accelerator keys.
\layout Enumerate

Consider the following excerpt from the introduction of one of the manuals:
\begin_deeper 
\layout Quotation


\family sans 
Return
\family default 
 and 
\family sans 
Enter
\family default 
 both refer to the same key.
 Some keyboards label the 
\family sans 
Return
\family default 
 key as 
\begin_inset Quotes eld
\end_inset 

Return,
\begin_inset Quotes erd
\end_inset 

 others as 
\begin_inset Quotes eld
\end_inset 

Enter,
\begin_inset Quotes erd
\end_inset 

 still others have two keys.
 LyX treats all of them as the same key, so we'll use 
\family sans 
Return
\family default 
 and 
\family sans 
Enter
\family default 
 interchangeably.
\layout Standard

Notice that the key name, 
\family sans 
Return
\family default 
, is in 
\family sans 
Sans
\protected_separator 
Serif
\family default 
, but 
\emph on 
only
\emph default 
 when it references the key itself! When I described how the manufacturer
 chose to label its keyboard, I used Roman and put the word in quotes.
 There is a semantic difference.
\end_deeper 
\layout Enumerate

Take the following command:
\begin_deeper 
\layout Standard


\family typewriter 
lpr -P
\family default 
\emph on 
printername
\layout Standard

Notice that the argument to the 
\family typewriter 
-P
\family default 
 option is in 
\emph on 
Roman Italics
\emph default 
 [i.e.
 emphasized].
 This is a case where you don't use 
\family typewriter 
Typewriter
\family default 
 for code, because you want the generic argument label to stand out.
 On the other hand, if you were specifying an argument, for example, 
\begin_inset Quotes eld
\end_inset 


\family typewriter 
lpr -Pduaneps
\family default 

\begin_inset Quotes erd
\end_inset 

, you'd leave it in 
\family typewriter 
Typewriter
\family default 
.
 
\end_deeper 
\layout Enumerate

Any LaTeX commands and code, and any 
\emph on 
unsupported
\emph default 
 LaTeX package names get set in 
\family typewriter 
Typewriter
\family default 
.
 For example, 
\begin_inset Quotes eld
\end_inset 


\family typewriter 
multicol
\family default 

\begin_inset Quotes erd
\end_inset 

 is the name of an unsupported LaTeX package, but 
\begin_inset Quotes eld
\end_inset 


\family sans 
book
\family default 

\begin_inset Quotes erd
\end_inset 

 is a supported LaTeX class.
\layout Standard

I also have some pointers for you:
\layout Description

Multi-word
\protected_separator 
names Use a 
\family sans 
Protected
\protected_separator 
Blank
\family default 
 between the words.
 E.
\protected_separator 
g.: 
\family sans 
Save
\protected_separator 
As
\family default 
, not 
\family sans 
Save As
\family default 
.
\newline 
I want the 
\family sans 
Protected
\protected_separator 
Blank
\family default 
 so that the name doesn't get split between two lines, which is visually
 disruptive.
\layout Description

Special
\protected_separator 
Terms These are things like the following:
\begin_deeper 
\layout Itemize


\family sans 
HFill
\family default 
 
\layout Itemize


\family sans 
VFill
\family default 
 
\layout Itemize


\family sans 
Table
\protected_separator 
Float
\layout Itemize


\family sans 
Figure
\protected_separator 
Float
\begin_deeper 
\layout Standard

Use 
\family sans 
Sans
\protected_separator 
Serif
\family default 
 font and, in the case of 
\family sans 
HFill 
\family default 
and 
\family sans 
VFill
\family default 
, capitalize the first two letters.
\layout Standard

Why are these terms special? They are concepts which the seasoned LaTeX-pert
 is familiar with, but which the new LyX user is not.
 I want them to stand out from the rest of the text, hence the use of 
\family sans 
Sans
\protected_separator 
Serif
\family default 
 for them.
\end_deeper 
\end_deeper 
\layout Description

Terminology
\family sans 
 
\layout Itemize

PostScript® is a registered trademark of Adobe Corp.
 
\emph on 
You must put the ® after it or we'll get sued!
\emph default 
 I also want it written as seen here, always capitalized.
 Not 
\begin_inset Quotes eld
\end_inset 

postscript®,
\begin_inset Quotes erd
\end_inset 

 or 
\begin_inset Quotes eld
\end_inset 

Postscript®
\begin_inset Quotes erd
\end_inset 

 but 
\begin_inset Quotes eld
\end_inset 

PostScript®
\begin_inset Quotes erd
\end_inset 

 - both of them capitalized, in the default font [i.
\protected_separator 
.e.
\protected_separator 
Roman].
 If you must, cut and paste it from here.
\begin_deeper 
\layout Standard

I am going to say this again:
\layout Standard
\added_space_top 0.37cm \added_space_bottom 0.51cm \align center 

\size larger 
\emph on 
You must put the ® after PostScript® or we'll get sued!
\layout Standard

I mean it! American companies like to sue anything that moves.
 If LyX gets in trouble because 
\emph on 
you
\emph default 
 forgot the ®, I will come after you with a running chainsaw.
 Got it?
\end_deeper 
\layout Itemize

It's a 
\bar under 
popup
\bar default 
; 
\begin_inset Quotes eld
\end_inset 

widget
\begin_inset Quotes erd
\end_inset 

 and 
\begin_inset Quotes eld
\end_inset 

dialog box
\begin_inset Quotes erd
\end_inset 

 are programmer terms, so don't use them.
\layout Itemize

The thing below the menu and above the editing window is the 
\bar under 
toolbar
\bar default 
.
\layout Itemize

Use the text 
\begin_inset Quotes eld
\end_inset 

->
\begin_inset Quotes erd
\end_inset 

 to quick-reference menu items.
 Example: 
\family sans 
File->Save
\family default 
.
 Notice that there are 
\emph on 
no spaces
\emph default 
 around the 
\begin_inset Quotes eld
\end_inset 

->
\begin_inset Quotes erd
\end_inset 

.
 See Below.
\layout Standard

The reason why I want no spaces around the 
\begin_inset Quotes eld
\end_inset 

->
\begin_inset Quotes erd
\end_inset 

 is to prevent LyX from splitting terms across lines.
 The same goes for using 
\family sans 
Protected
\protected_separator 
Blank
\family default 
s between multi-word terms.
 The split would be visually disruptive.
\layout Standard

As for the terms 
\begin_inset Quotes eld
\end_inset 

popup
\begin_inset Quotes erd
\end_inset 

 and 
\begin_inset Quotes eld
\end_inset 

toolbar
\begin_inset Quotes erd
\end_inset 

, if at some point I [or a future editor] need to change those, 
\emph on 
I'll
\emph default 
 take care of that.
 That's my job, after all.
 I want all of you, however, to use those terms.
 It will make any future switch much, much easier for either me or my successor(
s).
\layout Section

Keys
\layout Standard

The canonical keyboard contains these keys:
\layout Itemize


\family sans 
C-
\family default 
 or 
\family sans 
Control-
\family default 
 
\layout Itemize


\family sans 
S-
\family default 
 or 
\family sans 
Shift-
\family default 
 
\layout Itemize


\family sans 
M-
\family default 
 or 
\family sans 
Meta-
\family default 
 
\begin_deeper 
\layout Standard

Self-explanatory.
 Be lazy and 
\emph on 
use the abbreviations
\emph default 
 whenever possible.
\end_deeper 
\layout Itemize


\family sans 
F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
\begin_deeper 
\layout Standard

The function keys.
 Most modern keyboards have all 12.
\end_deeper 
\layout Itemize


\family sans 
Esc
\family default 
 
\begin_deeper 
\layout Standard

The 
\begin_inset Quotes eld
\end_inset 

Escape key.
\begin_inset Quotes erd
\end_inset 


\end_deeper 
\layout Itemize


\family sans 
Insert
\family default 
 
\family sans 
Delete
\family default 
 
\family sans 
Home
\family default 
 
\family sans 
End
\family default 
 
\family sans 
PageUp
\family default 
 
\family sans 
PageDown
\begin_deeper 
\layout Standard

These are the 6 keys that appear above the cursor keys on many PC keyboards.
 Consider them as part of the standard motion keys.
\end_deeper 
\layout Itemize


\family sans 
Left Right Up Down
\begin_deeper 
\layout Standard

The four standard motion keys.
 There is no need to put the word 
\begin_inset Quotes eld
\end_inset 

arrow
\begin_inset Quotes erd
\end_inset 

 anywhere, since that's obvious.
\begin_float footnote 
\end_deeper 
\layout Standard

Same goes for 
\begin_inset Quotes eld
\end_inset 

cursor key
\begin_inset Quotes erd
\end_inset 

.
 Even the word 
\begin_inset Quotes eld
\end_inset 

key
\begin_inset Quotes erd
\end_inset 

 after one of these may be redundant in certain situations.
\end_float 
 
\layout Itemize


\family sans 
Return
\family default 
 and 
\family sans 
Enter
\family default 
 
\begin_deeper 
\layout Standard

I won't throw a hissy fit if you use one instead of the other.
 I'd prefer if you used 
\family sans 
Return
\family default 
 over 
\family sans 
Enter
\family default 
, but it's okay if you slip up and forget.
 Since these two keys are bound to the same function in LyX, it doesn't
 really matter.
\end_deeper 
\layout Standard

You do not need to explain everywhere what the 
\family sans 
Meta
\family default 
 key is or where the 
\family sans 
Left
\family default 
 key is, et cetera.
 The user isn't stupid.
 Also, someone will document anything that isn't clear [e.
\protected_separator 
g.
\protected_separator 
the 
\family sans 
Meta
\family default 
 vs.
 
\family sans 
Alt
\family default 
 problem] someplace in the introduction.
 No need for you to repeat someone else's work.
\layout Section

Cross-References and Labels
\layout Standard

Use the following labelling conventions:
\layout List
\labelwidthstring 00.00.0000

sec:xxx Use this for 
\family sans 
Section
\family default 
s as well as 
\family sans 
Chapter
\family default 
s, 
\family sans 
Subsection
\family default 
s, 
\family sans 
Subsubsection
\family default 
s, etc.
\layout List
\labelwidthstring 00.00.0000

eqn:xxx Use this for Equations.
 Right now, only 
\noun on 
David Johnson 
\noun default 
should have to worry about this.
\layout List
\labelwidthstring 00.00.0000

tbl:xxxx Use this for tables inside of a table float.
\layout List
\labelwidthstring 00.00.0000

fig:xxx Use this for figures inside of figure floats.
\layout Standard

Additionally, you should put the label at one of two locations:
\layout Enumerate

The 
\emph on 
beginning of the paragraph
\emph default 
, after a section heading, or at the beginning of captions, etc.
 It should be the first thing on the first line.
 Don't put a space betweeen it and the first word.
\layout Enumerate

If there is no paragraph after a section heading, put it at the 
\emph on 
end of the last line.

\emph default 
 
\begin_deeper 
\layout Standard

Example: You have a 
\family sans 
Section
\family default 
 which is immediately followed by a 
\family sans 
Subsection
\family default 
 heading.
 This is a case where you need to put the label at the end of the 
\family sans 
Section
\family default 
 heading.
 I know it looks ugly; not much we can do about that, though.
\end_deeper 
\layout Section

Language
\layout Standard

All contributions to the documentation must be in English.
 I don't care if it's British or American English.
 I will proofread for glaring mistakes and fix them.
\layout Standard

Don't get hung up on semantics.
 English is a flexible language, and just because your Mothertongue-to-English
 dictionary gives only one translation for a word doesn't necessarily mean
 it's so.
 We've had some discussions and misunderstandings on the Developers' List
 because of this very problem.
 If something is unclear [or just plain weird] due to a translation problem,
 I can fix it.
\layout Section

Consistent Grammar Style 
\layout Enumerate

You are 
\begin_inset Quotes eld
\end_inset 

we
\begin_inset Quotes erd
\end_inset 

.
\begin_deeper 
\layout Standard

When you speak, you speak for the LyX Team, so use 
\begin_inset Quotes eld
\end_inset 

we
\begin_inset Quotes erd
\end_inset 

 instead of 
\begin_inset Quotes eld
\end_inset 

I
\begin_inset Quotes erd
\end_inset 

.
\end_deeper 
\layout Enumerate

The reader is 
\begin_inset Quotes eld
\end_inset 

you
\begin_inset Quotes erd
\end_inset 

.
\begin_deeper 
\layout Standard

Whenever you want to say something to the reader, use 
\begin_inset Quotes eld
\end_inset 

you,
\begin_inset Quotes erd
\end_inset 

 not some contorted construction to avoid being too informal.
 
\end_deeper 
\layout Enumerate

Write as if you're talking with a friend.
 
\begin_deeper 
\layout Enumerate

Think that way when you write.
 Play the dialogue in your mind.
\layout Enumerate

Be as informal as you please [without being rude].
\end_deeper 
\layout Enumerate

AVOID the passive voice:
\begin_deeper 
\layout Enumerate

No: 
\begin_inset Quotes eld
\end_inset 

It is felt that this name best explains the command's purpose.
\begin_inset Quotes erd
\end_inset 

 You know full well who wrote the command: 
\begin_inset Quotes eld
\end_inset 

The LyX Team felt ...
\begin_inset Quotes erd
\end_inset 

 Or, better yet, 
\begin_inset Quotes eld
\end_inset 

We felt that ...
\begin_inset Quotes erd
\end_inset 


\layout Enumerate

Things don't happen by magic - somebody or something did it.
 Only politicians use the passive voice to cover up actions.
 If LyX reformats a paragraph, write, 
\begin_inset Quotes eld
\end_inset 

LyX reformatted the paragraph.
\begin_inset Quotes erd
\end_inset 

 If 
\family typewriter 
ispell
\family default 
 makes changes, write, 
\begin_inset Quotes eld
\end_inset 


\family typewriter 
ispell
\family default 
 changes the document.
\begin_inset Quotes erd
\end_inset 


\begin_deeper 
\layout Standard

Rule of thumb: any sentence you can express as, 
\begin_inset Quotes eld
\end_inset 

It was done by foo,
\begin_inset Quotes erd
\end_inset 

 you can express as, 
\begin_inset Quotes eld
\end_inset 

Foo did it.
\begin_inset Quotes erd
\end_inset 

 Much nicer.
\end_deeper 
\layout Enumerate

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 byzantine.
 With a little effort, you can wean yourself off of it.
\layout Enumerate

I 
\emph on 
will make you rewrite
\emph default 
 anything in the passive voice.
 It's awkward and hard to read.
\end_deeper 
\layout Enumerate

Use the term 
\begin_inset Quotes eld
\end_inset 

mouse
\begin_inset Quotes erd
\end_inset 

 for both the physical pointing object [mouse, joystick, touch pad, track
 ball, etc.] and the mouse cursor which the physical object moves about the
 screen.
\layout Enumerate

Use the term 
\begin_inset Quotes eld
\end_inset 

cursor
\begin_inset Quotes erd
\end_inset 

 for the little blinking vertical bar that indicates where text can/will
 appear next.
\layout Enumerate

Be 
\emph on 
clear, concise, 
\emph default 
and 
\emph on 
to the point
\emph default 
.
 KISS = 
\begin_inset Quotes eld
\end_inset 

Keep It Short and Sweet
\begin_inset Quotes erd
\end_inset 

 [or, 
\begin_inset Quotes eld
\end_inset 

Keep It Simple, Stupid!
\begin_inset Quotes erd
\end_inset 

]
\begin_deeper 
\layout Itemize

Do 
\emph on 
not
\emph default 
 write paragraph after paragraph of verbage.
 
\layout Itemize

Get to the point.
\layout Itemize

Take a look at the manual for a commercial word processor --- it's a fine
 example of how 
\series bold 
NOT
\series default 
 to write documentation.
 It's all pithy, substanceless verbage, and its 
\emph on 
utterly useless!
\emph default 
 
\end_deeper 
\layout Enumerate

Avoid being pedantic like The Plauge!
\layout Enumerate

In the same vein, don't write more than you have to.
 You're not working in a vacuum --- refer freely to other parts of the manual
 [and other parts of other manuals].
 Even if that 
\begin_inset Quotes eld
\end_inset 

other part of the manual
\begin_inset Quotes erd
\end_inset 

 is incomplete or empty, refer to it.
 Someone will fill it in.
\layout Enumerate

On the other hand, BE THOROUGH!
\begin_deeper 
\layout Enumerate

You are documenting 
\emph on 
features
\emph default 
, not widgets, not how the source code is organized.
 
\layout Enumerate

Stay on topic --- one 
\family sans 
Section
\family default 
 should cover 
\emph on 
one
\emph default 
 feature.
 Use 
\family sans 
Subsection
\family default 
s and further subdivisions to group things if you're documenting several
 related features in a single 
\family sans 
Section
\family default 
.
\layout Enumerate

Describe EVERYTHING related to that feature, no matter where it is.
\begin_deeper 
\layout Enumerate

Example: Paragraph Indenting.
 Several popups control its behavior.
 You would document 
\emph on 
all
\emph default 
 of this: which popups control it, when you use which setting on which popup
 to do which operation, et cetera, et cetera, et cetera.
\layout Enumerate

I've had people only document one popup --- literally.
 This added off-topic information and only described half of the feature,
 since other menus, popups, and even unbound functions contained additional
 stuff.
\newline 
I get 
\emph on 
really
\emph default 
 cranky when that happens, because it means 
\emph on 
I 
\emph default 
end up fixing it.
 Bad help is worse than no help at all.
\end_deeper 
\layout Enumerate

Remember, there are people who will reference 
\emph on 
your
\emph default 
 section, just as you're referencing someone else's.
 You do want what you write to be useful, don't you?
\end_deeper 
\layout Enumerate

NEVER NEVER 
\series bold 
NEVER 
\emph on 
EVER
\series default 
\emph default 
 treat the reader as if she is stupid:
\begin_deeper 
\layout Enumerate

No dumbing-down!
\layout Enumerate

No talking down to the reader!
\layout Enumerate

The reader is smart enough to know what a mouse is.
\layout Enumerate

The reader is smart enough to know how to use a keyboard, including the
 
\family sans 
Shift-
\family default 
, 
\family sans 
Control-
\family default 
, and 
\family sans 
Meta-
\family default 
 keys.
 [
\emph on 
I
\emph default 
 explain that 
\family sans 
Meta-
\family default 
 is the 
\family sans 
Alt-
\family default 
 key on many keyboards in the introductions of every one of the manuals,
 so you don't need to.]
\layout Enumerate

The reader is smart enough to know that 
\begin_inset Quotes eld
\end_inset 

at the cursor
\begin_inset Quotes erd
\end_inset 

 means 
\begin_inset Quotes eld
\end_inset 

where the text cursor is sitting right now, in the buffer currently visible.
\begin_inset Quotes erd
\end_inset 

 
\size small 
[Anything more than the word 
\begin_inset Quotes eld
\end_inset 

cursor
\begin_inset Quotes erd
\end_inset 

 is, IMO, superfluous and I will delete it.
 So, save yourself the typing, save me the editing, and save the reader
 the strain of sifting through extra verbage that adds no content.]
\layout Enumerate

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.
\end_deeper 
\layout Section

Tools
\layout Standard

I want to make it easy for everyone when it comes to documenting things.
 Some features are incomplete.
 Some you might not know everything about.
 Sometimes, you may want to comminucate something to me or the reader or
 other DocTeam members.
 Sometimes, you may want to 
\begin_inset Quotes eld
\end_inset 

speak for yourself;
\begin_inset Quotes erd
\end_inset 

 you want to say something that is your personal opinion and using 
\begin_inset Quotes eld
\end_inset 

we
\begin_inset Quotes erd
\end_inset 

 would be inappropriate.
\layout Standard

For occasions like those, I've designed two mechanisms:
\layout Description

Personal
\protected_separator 
Notes: These are footnotes.
 They begin with the following:
\begin_deeper 
\layout Standard

Note from 
\noun on 
Name of Person
\noun default 
:
\layout Standard

using the 
\noun on 
Noun Style
\noun default 
 for the person's name.
 The rest of the footnote is the actual comment.
 If the comment is too large to put in a footnote, put it in a 
\family sans 
Quotation
\family default 
 paragraph environment instead.
\layout Standard

Use these when you need to quote a comment by someone, and want to identify
 that person.
\end_deeper 
\layout Description

Author's
\protected_separator 
Notes: These go in the body of the text, in brackets.
 The bracket are in the defaul character style, but the note itself is emphasize
d.
 Begin with the words, 
\begin_inset Quotes eld
\end_inset 


\emph on 
Author's Note:
\emph default 

\begin_inset Quotes eld
\end_inset 

 and end with 
\begin_inset Quotes eld
\end_inset 

---
\begin_inset Quotes eld
\end_inset 

 followed by your initials.
 Here's an example: [
\emph on 
Author's Note: This is an example note.
 ---jw
\emph default 
].
\begin_deeper 
\layout Standard

You should use these for the following purposes:
\layout Itemize

You need to contradict something you just wrote because the feature isn't
 quite ready yet, but you want to document what it will do.
\layout Itemize

You need to leave a note for yourself.
\layout Itemize

You need to leave a note for the editor or the other DocTeam members.
\layout Itemize

You need to point something out to the reader that doesn't fit into the
 context of the current paragraph.
\end_deeper 
\layout Standard

You are also free to use footnotes on their own in addition to the personal
 notes and/or author's notes.
 I've frequently used footnotes to \SpecialChar \ldots{}
 well, to comment on parts of a section
 without putting the commentary into the body of the text.
\layout Section

Content - What Goes Where
\layout Standard

This is 
\emph on 
very
\emph default 
 important, so PAY ATTENTION!
\layout Standard

I do not want 
\family typewriter 
Tutorial.lyx
\family default 
, 
\family typewriter 
Reference.lyx
\family default 
, and 
\family typewriter 
UserGuide.lyx
\family default 
 to all repeat the same dumbed-down drivel, like the manuals for certain
 commercial wordprocessors do.
 That's useless.
 It's a waste of our time, too.
 I want the manuals to dovetail together, to interface with one another.
 In principle, we use 
\family typewriter 
Reference.lyx
\family default 
 as a base and build the others on it.
 
\layout Standard

You see, in the past, whenever someone wanted to document a new feature
 they added, they either wrote a mini-doc and stuck it into the documentation
 directory, or they added a new section to 
\family typewriter 
Main.lyx
\family default 
.
 They tried to explain what their new feature did, but then needed to explain
 how to bind keys to it, how to use it, provide examples,
\layout Quote

...and on
\layout Quote

...and on
\layout Quote

...and on.
\layout Standard

The result was a totally bloated, totally unnavigable 
\family typewriter 
Main.lyx
\family default 
.
 I wanted to change, which is why I ended up as editor of the DocTeam.
 In that time, I started a major reworking, which included the writing of
 
\family typewriter 
UserGuide.lyx
\family default 
, over half of which is my own work.
 I don't want all that work to be for nothing.
 I don't want the docs to fall back into a mess.
\layout Standard

With that in mind, I have some instructions for how to keep things organized:
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
Intro.lyx 
\family default 
Please, don't touch this file.
 It's essentially complete, anyhow.
 Only the editor(s) and/or maintainer should make changes to this, as this
 file contains info about how to contribute to the doc project.
 That's really the only stuff that should need to change, and even then,
 only when a new maintainer comes along.
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
HowDoI-.lyx
\family default 
 is the FAQ.
 There are some people working on this, so contact them if you want to contribut
e.
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
UserGuide.lyx 
\family default 
This file is complete.
 Any changes should be for updates 
\emph on 
only
\emph default 
.
 DO NOT ADD new features to here willy-nilly.
 Let the editor/maintainer decide if --- and when --- new sections go in
 here.
 Place any new features in\SpecialChar \ldots{}

\layout List
\labelwidthstring 00.00.0000


\family typewriter 
SpecialTools.lyx
\family default 
 This is where all new features go from now on.
 It's in the style of a bound journal --- each section is an 
\begin_inset Quotes eld
\end_inset 

article
\begin_inset Quotes erd
\end_inset 

 from the author of the feature.
 Also, anyone who writes a 
\family typewriter 
.layout
\family default 
 file for a new document class should write a section describing that new
 class and how to use it.
 That also goes here.
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
Tutorial.lyx
\family default 
 It ain't complete --- yet.
 But, someone's working on it, and when he finishes, there won't be much
 else to add.
 
\newline 
The purpose of the 
\emph on 
Tutorial
\emph default 
 is to get the users on their feet, especially and specifically if they've
 never used LaTeX or an environment-based word-processor before.
 Once it's done, the only new things that should go into the 
\emph on 
Tutorial
\emph default 
 are excersizes for how to use new document classes, [if even that].
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
Customization.lyx
\family default 
 It's a mess.
 Complete disaster! [
\emph on 
sob
\emph default 
!]
\newline 
Someday, a complete description of how to write new 
\family typewriter 
.layout
\family default 
 files will be in here.
 And a description of the new 
\family typewriter 
.lyxrc
\family default 
 format.
 And a description of how to tailor LyX for use with languages other than
 English, or how to use LyX in a multi-lingual setting.
 And how to customize your keyboard bindings.
 Right now, there's a mini-tutorial about how to set up your Linux print
 daemon.
 That's the only thing which is truly complete.
 Anything else, you can change.
\layout List
\labelwidthstring 00.00.0000


\family typewriter 
Reference.lyx
\family default 
 I'd prefer to completely finish this one before doing anything else, but
 that's unrealistic.
 LyX keeps changing so much that I think the 
\emph on 
Reference Manual
\emph default 
 will be the last one completed.
 However, I'd like it if the developer's would add entries anytime they
 create a new function or popup.
 That would help things immensely!
\the_end
