README.Documentation

by John Weiss [9/1/96] weissjp@colorado.edu


================
1.  Introduction

    The purpose of this file is, primarily, to provide a style sheet
    and helpful hints to those wishing to help with the documentation
    project.  If you're actually looking for documentation, there are
    6 files in LyX format which you can read from within LyX.  Check
    out the Help menu to load Intro.lyx.  It's a good place to start.

    The reason I'm writing this file is to stop clogging the LyX
    Developers' List with my whining.  I figured putting a README in
    the source code distribution would lay all further questions to
    rest.  Also there were some things I stated, in fragmented form,
    in several mail messages to the list.  It was time to do
    something more formal.
    

================
2.  Why a separate documentation project?  Can't the developers do it?

    In a word, no.  They're too busy adding features and squishing
    bugs.

    Also, g++ is far more forgiving of style changes than a human
    brain.  As long as the code is correct, g++ will happilly compile
    it, and compile it the same way from machine to machine.  Human
    brains are far less forgiving and far more individualized.  So,
    the documentation needs to all be in a uniform style, in addition
    to being grammatically correct and easily readable.  That's a
    pretty big undertaking - which is why I volunteered to
    administrate the docs in the first place!  Lars has enough to do
    maintaining the code, anyways!


================
3.  Okay, wiseguy, so what *is* "correct" style, anyway?

    Pretty much anything; English is a pretty flexible language.

    Oh, I guess that's the first requirement -

    a) 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.

    b) 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.

    c) Use an informal writing style.  Address the reader as "you."
    Just pretend you're talking to a good friend.

    d) Each documentation file has its own purpose and its own
    audience.  If you have a submission for the documentation, gear
    it towards one of these files.  Or two.  Or three.  Example: if
    you sent me an in-depth, blow-by-blow explanation of how to use a
    new feature, don't tell me to put it in UserGuide.lyx, because
    I'll: A.) reject the submission; B.)  put it in Tutorial.lyx; or
    C.) Tell you to rewrite it and split it into two submissions, one
    for UserGuide.lyx and one for Tutorial.lyx.

    Oh, and if you do send me documentation for a new feature, I
    *will* ask you for an entry to Reference.lyx if you didn't
    provide one.  :) Even if your submission is fine and ready to go
    into the documentation, if you didn't provide me with an entry to
    Reference.lyx [or the Tutorial.lyx], I'll probably ask you for
    one.  So, it works the other way around, too.  ;)

    e) Use "we" instead of "I" - when you write something in the
    documentation, you are speaking for the entire LyX Team, not just
    yourself.  [If you do want to make a personal observation, or
    need to leave a note for yourself, use one of the methods
    described below.]

    f) In the beginning of each document is a description of the font
    conventions.  Use it:

        - Typewriter ==> program names, filenames, and code examples.

        - Sans Serif ==> references to sections of other manuals.

        - Noun Style ==> people's names.

        - Emphasized Style ==> names of menus, buttons, and LyX
					      commands.
					      Also used in Editor's Notes.

    We do not use boldface for anything.  

    The reference manual, Reference.lyx, uses a somewhat different
    convention.  There's actually a template for entries included in
    Reference.lyx - you should cut & paste it and just fill in the
    blanks.

    g) Personal Notes.  

    These are footnotes.  They begin with the words,

     "Note from <SoAndSo>:"

    where the <SoAndSo> is someone's name in Noun Style.  The rest of
    the footnote is the actual comment.  Use this if you want to make
    a personal remark, or if you want to include something someone
    said on the Developers' List.

    h) Editor's Notes.

    Unless you REALLY get involved with us and become part of the
    documentation team, you won't need to use these.  These are
    either in a footnote or in the text itself surrounded by a [].
    They have the following format:
    
        [Editor's Note: This is the note itself -<ii>]
    
    where <ii> are the author's initials.  The entire note is in
    emphasized style.
    
    I've used these for the following purposes:
    
        -I've needed to contradict something I just wrote in the
	    documentation because a feature isn't quite ready yet.
    
        -I need to explain why a section is empty, or why an old
	    defunct section is still included.
    
        -I'll use it as a reminder to myself, perhaps including a
	    rough outline of what I want to put in an empty section.
    
        -I'll use it to leave a "bookmark" for myself so I can find
	    where I stopped editing last time.
    
    You could also use these to leave a note for me, or someone else
    in the documentation team.



================
4.  So, I have new section to include in the documentation.  How do I
    submit a patch?

    I'd prefer that you didn't.  Remember what I said about human
    brains compared to a compiler?  If you give me a patch, but the
    patch has typos, grammar errors, stylistic boo-boos, etc., it
    could take me months to find them all!  In the mean time,
    everyone on the list is wondering why we keep getting "how do I
    do this?" messages...
    
    So, don't send a patch, send me a .lyx file.  If you want to give
    me a new section to include in the documentation, send me a
    mini-doc with the new section, and tell me where you'd like me to
    merge it.
    
    If you find a typo, a spelling error, or some section you think
    is poorly written, LET ME KNOW!  I'll change it myself.
    
    Example: A while back, Asger Alstrup, a member of the LyX Team,
    sent me a documentation patch.  Here's what I did with it - 1.) I
    made duplicates of the documentation and applied the patch.  2.)
    I loaded up LyX with both versions of all 7 doc files.  3.) I
    checked the patch, line by line.  Turns out Asger had only made
    changes to 1 or 2 of the files; all the others only had changes
    to the preamble.  so, 4.) Deleted the patched files that had no
    real changes.  5.) I took the files that had minor changes,
    changed my copies by hand, and deleted the patched files.  6.)
    For the remaining changed files, I looked through the patch, line
    by line, to find what Asger had changed.  7.) I then compared the
    patched files to the originals, looked at what had changed, fixed
    typos, rewrote a few sentences, et cetera, et cetera.
    
    It's taken much, much less time when someone mails the
    Developers' List and says, "Hey, there's a goof in
    SuchAndSuch.lyx that you need to fix, John."  Then either I or
    David Johnson would fix it.
    
    Oh - I *do* have printed copies, and I *do* intend, every few
    months, on hand-proofreading the printed copies to find any
    errors I've missed, or to see what needs to be rewritten, and so
    on.
    

    Here's how to submit a minidoc for inclusion into the
    documentation: 

	    - Put the minidoc[s] in a tar file and gzip it.

	    - Name the file as follows:

		    myname-yymmdd-lyxdoc.tgz

	      where "myname" is your last name, and "yymmdd" are the
		 numbers of the year, month, and day when this file was
	      made.  Note that the first example is a gzipped tar
	      file, while the second

	    - Send the uuencoded tarfile to:
    
                    lyxpatches@via.ecp.fr 
    
          and then send a mail to the Developers' Mailing List at
	     lyx@via.ecp.fr describing what you've sent in.


    Be sure to tell me what these minidocs are for and where you
    intended for them to go.  You can leave me a note in the tar
    archive, in the email to the Developers' Mailing List, or even in
    the .lyx files themselves.



================
5.  John, I'm one of the members of the Documentation Team.  Does
    comment #4 apply to David Johnson and the rest of us on the Doc
    Team? 

    Well, that depends.  Here's an example.  David Johnson is now
    officially in charge of HowDoI-.lyx.  Since that file is now his
    baby, he can send me patches for it and I'll apply them almost
    blindly.  On the other hand, suppose he wanted to add a section
    to the tutorial.  Since Tutorial.lyx is *my* baby, I'd prefer to
    insert things by hand so that they stylistically mesh with what
    I've already written.


    Here are the 7 documentation files, and who's working on
    them:

    Intro.lyx ==> No one, but this file is mostly complete.

    HowDoI-.lyx ==> David Johnson.
    
    Tutorial.lyx ==> John Weiss.
    
    UserGuide.lyx ==>  The Documentation Team.

    LaTeX-Tips.lyx ==> No one, at the moment.  :{

    Customization.lyx ==> No one.  :{
    
    Reference.lyx ==> No one, but I've had an offer for some help.
			    Besides, this guy is special - it's going to be so
        		    huge that we'll need many people to help out with
        		    it.  Stay tuned...



================
6.  John, I want to join the Documentation Team.

Great!  We could always use the help, especially with
Reference.lyx!

Right now, the Documentation Team consists of:

    John Weiss
    David Johnson

...with offers of help from:
    
    Rick Forrister
    Chris Wilber

Want to join?  Email me a weissjp@monsoon.colorado.edu and we'll
talk!








================
That concludes this README.  Let me know if it's unclear in
spots, and I'll fix it!


John Weiss

9/1/96
