Previous Next Contents

3. So how do I actually start preparing one of these documents?

3.1 Start with an outline

Make the outline general, don't worry about all the details yet. Pencil in your thoughts and questions, set it aside, look at it a day or two later. Somewhat comfortable with it? Try sharing the outline of ideas with another person on the Insulin Pumpers developer's site. Don't be shy, since this is just the beginning of an idea. Nobody expects your work to be perfect.

When you're comfortable with your progress so far, add some "filler" material to your thoughts / outline. Try incorporating some of the ideas and feedback you got from the other group members (as well as anyone else you may talk to and share things with). Check out their suggestions, especially if they involve technical details. It's surprising how quickly the page will fill up.

3.2 Should I format the document now?

Don't worry about the grammar or formatting yet, since it's still early in the process (we can't paint the house until the foundation is built). What you should be spending your efforts on now are the overall thoughts and ideas. Don't be afraid to share your thoughts, feelings, ideas.

As mentioned above, remember that readers will need to be frequently reminded to check the details of "recommendations" and "suggestions" with their health care teams before acting on any information presented in your FAQ. (A disclaimer in the beginning of the document usually serves this purpose).

3.3 Check the facts ...

If your FAQ / HowTo / essay / article contains factual or mathematical info, now is a good time to check the info. Your fellow developers are glad to help with things like this. Each of us has different areas we are comfortable with and will gladly share our expertise with others.

3.4 Spell checking, grammar, etc.

Spell checking and simple grammar checking can be done now. If you have transferred your original outline / thoughts to your computer, your word processor spell checker can get a good workout here. Note that your dictionary may not contain a lot of the medical and technical terms which you will be using, so be aware of that.

3.5 Now it's time to format the document

Formatting your FAQ really does not need to be any more complicated than breaking it up into paragraphs and deciding how you want the sections organized (what material comes first, what comes next, which parts of the document should be section headings, etc.). Note: Save your document as a .txt (text) file, for use with the editing tools we will discuss later on.

Bob's note: When I started working on my NEW PUMP FAQ, I had no idea how to format the document, prepare it with the tools for web presentation, etc. So, I resorted to the same trick I used in school when I was a kid (oh, that was soooooo long ago). I checked out someone else's document (one of the ones which Michael had prepared), copied it, removed his text, inserted a small portion of mine, and looked at it. It actually started to make sense - MJ chipped in when I stumbled, Michael encouraged me to try some things I had forgotten years ago, and it all came together. As I got more comfortable, the document grew and took on a personality ;-)

The more complicated tasks can now be shared, passed off entirely to someone else if you would rather not worry about them, or you can be walked through these steps by another helper. The next several steps (doing the "SGML markup" and "debugging") admittedly are somewhat different than what you may have done, but it's actually pretty neat stuff to learn!! Again, all or some of these tasks can be handled by others if you are not comfortable with them.


Previous Next Contents