[Mono-docs-list] Monkey Guide Evangelism

[Ben Maurer]

Hello everyone!

Over the last few days, as many of you may know, I have been
evangelizing some Mono Handbook stuff. A lot of it has had to do with
getting the thing proofread. I wanted to outline what we have done in
the last few days, and what we still need to do.

      * Today, I checked in a patch for the make file that validates the
        HTML with xmllint, and refuses to build if it fails to validate
        as XHTML. Hopefully, this means we can curtail invalid XML
        preventing users from browsing. To make this useful, you must
        ensure that you *attempt to build the monkeyguide before you
        check in changes*. This is something that I would expect
        anyways.
      * I ran tidy on all the files that were not validating as XHTML.
        Now we have a clean slate, lets keep it this way.
      * I did some major spell checking. There is a lot of work that
        needs to be done. Right now, one of the best ways to do it is to
        find commonly misspelled words, and use our friends grep and
        sed. Some commonly misspelled words in monodoc include (these
        are the *wrong* versions, to make grepping easy 
                accross
                behaviour
                enviroment
                invokation
                mantain
                neccessary
                occured
                recieve
                seperate
                writeable
        I have not gotten to grepping for all of these, maybe one of you
        would like to attempt to fix some of these misspellings ;-).
        Please note, use *American* spellings. Also r-e-c-e-i-v-e. i
        before e except after c or when it sounds like a as in neighbor
        or weigh. :D 
      * We need to move all the code samples to external .cs files. This
        has a few advantages:
              * It will allow use to do spell checking more easily, as
                we won't have to wade though 'misspelled' variable
                names.
              * We can automatically compile all the samples with mcs,
                to make sure they actually work (I found some that would
                not compile, because class names were misspelled [namely
                System.Environment])
              * We can use automated tools to convert to other languages
                (like VB) with available tools.
              * We can colorize the C# code before we put it into the
                html.
Right now, there are some small tasks that you can take when you write
monkeyguide that will make our lives easier in the future:
     1. Please run `aspell' on your file *before* you check it in.
     2. Please give your new docs a proofread before you check them in.
     3. If you are creating a new file, please run `tidy' on it before
        you first check it in

Please note that I do not want these items to prevent anyone who wishes
to contribute from doing so. In order to prevent that, I am making an
offer to anyone who wishes to write handbook content. If you write
content, which is reasonable first draft quality, and run it though
`aspell' to check for obvious spelling errors, I in turn will be happy
to review your grammar. If you send me your spell-checked .html file, I
will gladly send you a diff with all the grammar fixes.

-- Ben