How to write a HowTo or FAQ document for the Insulin Pumpers
Web Site
Bob Burnett & Mary Jean Renstrom
Version 1.2.2 - 3-25-99
This document presents some "basic ideas and procedures" to get you
started writing documents for the Insulin Pumpers Web Site. It is a
collaborative effort, produced by Bob Burnett and Mary Jean Renstrom.
______________________________________________________________________
Table of Contents
1. Overview
2. Let's Start Simple
2.1 What is a FAQ?
2.2 What is a HowTo?
2.3 Where will my document go on the Insulin Pumpers web site?
3. So how do I actually start preparing one of these documents?
3.1 Start with an outline
3.2 Should I format the document now?
3.3 Check the facts ...
3.4 Spell checking, grammar, etc...
3.5 Now it's time to format the document
4. What "tools" do I need?
5. What to do with your brand new Ip-dev account.
5.1 Customizing your account
5.2 Creating your own copyright notice.
5.2.1 With a "standard" FTP client...
5.2.2 For America Online users...
6. What happens after the document is written?
6.1 What is SGML and how do I use it?
6.2 How do I get my document onto the website?
7. A few words of encouragement
8. Copyright Notice
______________________________________________________________________
1. Overview
Writing FAQs and HowTo documents requires some effort and thought on
the part of the author(s). What people have to say and share is the
most important part of this process.
How this information gets presented to others (the format of the
presentation) is a separate task from authoring the documents. There
will always be someone around to assist with compiling the experiences
and thoughts of other pumpers in a standardized format for the web
pages. This is actually fairly easy to do, provided we keep talking to
each other and asking others to help.
2. Let's Start Simple
2.1. What is a FAQ?
The term FAQ stands for Frequently Asked Questions. This term is often
used to describe documents which summarize questions repeatedly asked
on a particular subject. A FAQ is usually somewhat informal - the
style of writing tends to be more along the lines of a friendly
conversation rather than a doctoral thesis.
A FAQ might summarize information presented over time in an online
discussion group, or might present an individual's own ideas on how to
solve particular problems. Whatever "slant" the FAQ takes, it should
be clearly stated in the beginning, so the readers know what to expect
from the document.
2.2. What is a HowTo?
A HowTo document is typically an explanation of a process or
procedure. It might be instructions for setting a Temporary Basal
Rate on an insulin pump, or it might lead someone through the steps
necessary to test their Blood Glucose using a BG meter. This document
is an example of a HowTo.
HowTo documents often appear in much the same fashion that a cooking
recipe might appear - a series of sequenced steps with any additional
required explanations included in each section. More involved
documents may also include cross references to other web sites to help
understand the process. (We will explain some of these "link" details
later on in this document).
It is important to realize that even though the format and styles of
FAQ and HowTo documents is "friendly", the documents should still be
factual, accurate and present information in a straightforward
fashion. If you are not sure of something, do not state is as "fact".
If something stated is an opinion, this needs to be clearly stated as
well.
Very Important Note: FAQs and HowTo documents are NOT intended to be
the final or definitive answer to complex medical questions, nor are
they intended to serve as replacements for competent medical guidance.
Authors need to keep this in mind when compiling the information they
are presenting.
Readers need to be constantly reminded to check the information or
suggestions with their health care team before adopting these
suggestions as part of their health management plan. This is usually
best done with a "standard disclaimer" appearing in the document(s).
Have we scared you off yet? Hope not, because preparing these
documents is actually quite straightforward. The following are some
tips and guidelines for preparing FAQs and HowTos for inclusion on the
Insulin Pumpers web site. These guidelines are not "gospel" (if
something is so important that it cannot be overlooked, we will state
it at the outset). The authors of this "HowTo" document have
experience in technical writing and have been active participants in
internet mail lists and newsgroups for a number of years. They have
authored or collaborated on several of the FAQs and HowTo documents on
the Insulin Pump's web site.
2.3. Where will my document go on the Insulin Pumpers web site?
Sometimes it is not immediately clear to the developers which section
on the Insulin Pumpers site the new document should belong to - FAQs
or HowTos. Don't worry - we will all discuss this as a group, take a
vote and find an appropriate home for your hard work.
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.
4. What "tools" do I need?
You don't need any fancy software to develop documents for the Insulin
Pumpers web site - everything we need is available on line in the
developer's area (thank goodness). Up until this point, you still do
not need to know anything more "technical" about preparing information
for Internet web pages than how to type an e-mail message.
"Useful tools" might include:
1. A text editor or word processing software (there is a text editor
available on the developer's site, if needed). Your files need only
be saved as .txt (non formatted text) files. We'll make them pretty
later on in the process.
2. An FTP "client", or FTP file transfer capability, to move files to
and from your computer. This is how the documents will get
transferred to the Web site. (O.K. if you really want to know, FTP
stands for "File Transfer Protocol"). The documents tend to get
large as they are worked on and typically become too large to
transfer as e-mail attachments.
FTP lets you quickly transfer large files to another computer.
3. A Telnet "client". This capability will allow you to access the
developer's page and use one of the tools to check your finished
work and convert it to the proper format for presentation. Telnet
is a network application that you can use to log in to one computer
(or device) on the Internet from another. It is faster than using a
"dialup" connection between the two computers.
If you don't have ftp or telnet on your computer, you may download
some simple versions from the Insulin Pumpers ftp site
. This will connect you to the "PUB"
directory on the FTP server. Click on the Microsoft link to continue
to the area where the FTP tools are located.
Clicking on the blue hypertext for each of the files will then
initiate a download process for the file. When the download manager
screen comes up, direct it to place these files in your Windows
folder. You will have to do this separately for each file. Download
the ftp, telnet, and telnet help files if you need them.
There are several of us who are comfortable with these tools and can
walk "new comers" through the steps for their use. You'll certainly
feel comfortable fairly soon with these basic utilities. The
important point here is that you are not on your own. Others will
gladly help if you ask!
5. What to do with your brand new Ip-dev account.
This is where the "magic" and "smoke and mirrors" stuff starts ...
You have been provided you with your own Ip-dev account on the server.
This account gives you access to the UNIX server through telnet and
you can use FTP to transfer files in and out of your account. You
have been given your own "username" and password for this account.
Your account comes as a "bare bones" version and you will need to
customize it a bit. This area is where we store our work in progress,
so it can be easily shared among the developers. You might want to
think of this account area as a "workshop" or work area.
5.1. Customizing your account
One of the first things you will need to do is load some basic Ip-dev
documents into your account so that you can use them when you are
writing FAQ's and HowTo's. You will need to load the file that
contains the copyright notice and the files that contain the images of
those little arrows that direct you forward and backward through the
sections of documents. Here is a list of instructions to follow:
Note: In these instructions, do NOT type the quotation marks as part
of the command. They are in the instructions to make the commands
easier to read.
1. Get connected to the internet in whatever way you normally do.
Note that you will not actually be going onto the internet, you
just need to have the connection open.
2. Login to the server with telnet. Use the user name and password
that you were given. See logging on to the server
for more guidance
on how to do this.
3. Once in telnet, you will need to create a "howto" directory for
your account. At the prompt (it says: "ns2") you should type the
following: "cd public_html" and hit enter. Be sure to leave a
space between cd and public.
4. Now type "mkdir howto" and hit enter. This creates a howto
directory in your account.
5. Now you should change directories to the one which contains the
copyright notice and the *.gif files (the little arrows). Type "cd
/home/sgml/public_html/lib" and hit enter. Type "ls" to get a list
of the contents of this directory. Copy the files to your howto
directory by typing the following commands: (Substitute your
username in the appropriate area. Be sure to include the spaces
after "cp" and before "/home".)
cp copyright.notice /home/yourusername/public_html/howto (hit enter)
cp *.gif /home/yourusername/public_html/howto (hit enter)
6. At this point you can logoff from telnet.
5.2. Creating your own copyright notice.
The copyright notice is a generic version and you will need to
customize it by adding your name and email address. We strongly
suggest that you download this into your word-processor and make the
appropriate changes there. You can save it as a text file and then it
can be easily inserted at the end of all your FAQ's and HowTo's
without retyping it each time. Here are the steps you need to follow:
Note - Don't type the quotation marks which appear in the instructions
below, they are included to "set aside" the exact letters to type.
5.2.1. With a "standard" FTP client...
1. For Windows 95 or NT users, go to a DOS prompt, type "ftp" (hit
enter). This will start your FTP client.
2. At the ftp> prompt, type "open home.bzs.org" (hit enter)
3. Enter your user name when prompted (hit enter)
4. Enter your password when prompted (hit enter)
5. At the ftp> prompt, type "cd public_html/howto" (hit enter). You
are now in your "personal" howto directory.
6. If you type "ls" (hit enter) you should see a list of the files in
your directory.
7. At the ftp> prompt, type "get" (hit enter)
8. When prompted for the remote filename, type "copyright.notice" (all
lower case letters) (hit enter)
9. When prompted for the local filename, type the full path to the
destination for this file, including the filename. (hit enter).
This will probably be the default storage directory for your word
processing documents.
NOTE: Your local file system (DOS, Windows, etc) may not recognize
the full filename and extension as it exists on the remote server.
You might want to save the file locally with a different name and a
.txt extension to make this easier to work with. You can rename it
when you transfer it back to the remote server.
10.
You will get a confirmation message telling you about the
throughput of the file transfer, then you will be returned to the
ftp> prompt when the transfer is complete.
11.
At the ftp> prompt, type "bye" (hit enter). This will log you off
the remote system.
12.
Open the copyright.notice in your word-processor and edit it by
inserting your name and email address in the appropriate areas.
There are some instructive comments in the file on how to do this.
Save the edited version so that you can merge it into your FAQ's
and HowTos.
Now, transfer the file back to the server, so you can include it in
your web page documents:
1. For Windows 95 or NT users, go to a DOS prompt, type "ftp" (hit
enter)
2. At the ftp> prompt, type "open home.bzs.org" (hit enter)
3. Type your user name (hit enter)
4. Type your password (hit enter)
5. At the ftp> prompt, type /"cd public_html/howto" (hit enter). You
are now in your "personal" howto directory and can transfer the
file from your local machine back to the server.
6. At the ftp> prompt, type "put" (hit enter)
7. When prompted for the local filename, type the full path name for
this file, including the filename and extension. (hit enter)
8. When prompted for the remote filename, type "copyright.notice" (all
lower case letters, be sure to include the period between copyright
and notice) (hit enter) The ftp transfer will proceed. You will see
a message telling you about the file throughput as it is
transferred. When the transfer is complete, you will be returned
to the ftp> prompt.
9. You can type "bye" (hit enter) to log off, or continue working on
the remote system.
5.2.2. For America Online users...
America Online offers a graphically interfaced FTP client. You can
navigate by clicking on icons instead of typing commands. (You will
not be able to "read" from other members' directories with this client
but it is convenient for getting things in and out of your directory.)
1. Sign on to AOL and click on the internet connection icon on the
"Welcome Screen". Click on the icon that says "internet extras".
Then click on "FTP".
2. Click on "Go to FTP" and then on "other site".
3. Type "home.bzs.org" in the box and check the box that says to ask
for login name and password. Click on "connect". Use the same
username and password that you used to get into the server with
telnet.
4. Highlight the line that says "public_html" and click on "open".
5. Highlight the line that says "howto" and click on "open". A list
of all the files that are in your "howto" directory should appear.
6. Highlight the file named "copyright.notice" and click on "Download
Now".
7. Direct the download manager to put it in your word-processor's
files so that you can edit it. Click on OK.
8. Now you can close all the FTP windows and sign off of AOL.
9. Open the copyright.notice in your word-processor and edit it by
inserting your name and email address in the appropriate areas.
There are some instructive comments in the file on how to do this.
Save the edited version so that you can merge it into your FAQ's
and HowTos.
6. What happens after the document is written?
6.1. What is SGML and how do I use it?
SGML stands for "Standard Generalized Markup Language" and is similar
to HTML in many ways. Documents formatted with SGML follow a specific
protocol regarding sectioning, sub-sectioning, and moving between
sections. The majority of the documents on the Insulin Pumpers
Homepage, including this one, are formatted with SGML. Those little
arrows to direct you forward and backward through the document are
part of the SGML formatting. SGML will automatically create its own
table of contents for all of the sections and sub-sections and present
it at the beginning of the article.
To prepare a document for SGML markup, the author needs to decide what
the major sections are and if there will be any subsections. Articles
/ FAQs / HowTos on the IP website will always have at least two
sections. One of the sections is the standard copyright notice which
appears at the end. The "body" of the document can be one section, or
broken into two or more. It depends on the complexity of the subject.
In addition, an "abstract" will need to be written. This is the
description which appears at the beginning of the article when it is
on the web site. It is automatically italicized and encased between
two horizontal lines. The abstract should be a brief synopsis of the
topics covered in the article.
To learn how to do the SGML markup, download the SGML Tools User's
Guide and the Example document into your directory. Here are the
specific steps to follow:
1. Open a ftp connection to home.bzs.org by typing "open home.bzs.org"
2. You will be prompted to enter your username and password.
3. Type "cd /home/sgml/public_html"
4. Type "ls" to see a list of the files in this directory.
5. Type "get guide.sgml". This puts the file into your current local
directory on your hard drive so that you can play with it. This
may be your Windows Desktop or somewhere in your word processor.
(To find out what your current local directory is, type "lcd ."
(note that is: "lcd {dot}"). The file will show up with all the
sgml tags so you can see what they look like. You may consider
printing these files (both the guide and the example) so that you
can really study the sgml syntax.
6. Type "get example.sgml"
7. Type "cd /home/yourname/public_html/howto"
8. Type "put guide.sgml". This will put the file into your howto
directory on the server. From here you will be able to translate
it into html so you can see what the document looks like on the
net.
9. Type "put example.sgml"
10.
Open a telnet connection to home.bzs.org
11.
Type "cd public_html/howto"
12.
Type "ls" to make sure that the guide and example files are
actually there.
13.
Type "sgml2html -I guide.sgml". This converts the user's guide to
html so that you can view it on the web with your browser. The
"-I" part adds the arrows to navigate through the sections.
14.
Type "sgml2html -I example.sgml".
15.
Minimize the telnet and ftp windows and navigate to your internet
browser prompt.
16.
Type "http://www.bzs.org/~yourname/howto". A list of the files in
your howto directory should appear.
17.
Locate the files named guide.html and example.html. These are the
main html files which contain the table of contents for each of
these files. Note that the sgml2html command created a separate
html file for each section of the documents. Open each of the
files to see how they look in hypertext. Print the documents out
and compare them with the sgml versions of the same documents.
By comparing the sgml and html versions of these files you can learn
how to use the sgml tags. You can ignore the part in the guide about
downloading the sgml tools. This has already done and the tools are
on the Unix server for us to use. The "meat" of the user's guide
starts with the section titled "Writing Documents With SGML-Tools".
Information on including links to other websites is included in the
section titled "Cross References". Once again, viewing both the html
and sgml versions of the user's guide will help you understand how
this works. Please note that there are some special characters which
need a "macro" in order to work in sgml. (A macro will substitute a
string of characters for the special character.) The user's guide
contains a complete list of these characters and their corresponding
macros. Again, if this is overwhelming, there are people on the IP
development list who actually enjoy doing SGML markups and will help.
6.2. How do I get my document onto the website?
You can learn to do this yourself, or ask another member to help. It
is not difficult, once you know where you are going! An overview of
the steps involved follows:
1. Upload the document via FTP to your howto directory.
2. Once the document is in your HowTo directory, you can access it
through a telnet connection. In telnet, type "cd
public_html/howto" to get to your directory.
3. You can now do any editing you need to with "joe", an on-screen
editor. Joe is a little funky to use, but handy for quick fixes.
To open the file so that you can edit it with joe, type "joe
filename.sgml". To learn how to use joe, refer to editing with joe
.
4. Open a second telnet window so you can check the SGML formatting
for bugs. Leave the first telnet window open so that you can edit
the document there. In the second telnet window, change to your
howto directory again and type "sgmlcheck filename.sgml". Note:
Substitute the name of your file for "filename". This check will
tell you which specific line(s) have problems with the SGML syntax.
Make any necessary corrections (in your first telnet window) and
run sgmlcheck again. If you run sgmlcheck and it just comes back
with the prompt, congratulations!! You don't have any errors and
can proceed to the next step.
5. After the SGML is bug-free, convert the document to html by typing
the following command: "sgml2html -I filename.sgml". This command
creates an html file for each section of your document as well as
the table of contents.
6. Now you can go onto the web and take a look at your document.
Leave the telnet windows open (minimize them) and go to
"http://bzs.org/~yourname/howto" to see what is there. ("yourname"
is your user name that you were given when you joined the IP-dev
group.) Open the document which is called filename.html. This is
the table of contents for your article with the sections and sub-
sections highlighted in blue hypertext. Read through your article
and test all links to other sites. Make sure that the formatting
is how you want it. If you need to make some changes, go back to
the telnet window which has the document open and use joe to make
changes. If the changes are substantial, you may want to go back
to the source file in your word-processor and make the changes
there, and upload it via ftp again. If you make any changes, you
will need to run the sgmlcheck and sgml2html commands again and ask
your browser to "reload" the document.
7. At this point, you can ask other Ip-dev list members to critique /
proofread the document by letting them know where to look for it.
8. When you are completely satisfied with the article's presentation,
think up a "hotlink" name and short description for the website and
let Michael know via e-mail. The hotlink is the hypertext which
appears on the website so others can access your article.
7. A few words of encouragement
We hope that this "HowTo" has been helpful to you. If you find any
areas which are "clear as mud" please let us know (Bob Burnett
bburnett@twcny.rr.com , and Mary Jean
Renstrom Mjrenstrom@aol.com ) and we will
try to confuse you, er, clear up the problem as much as we can. :)
Don't feel like you have to learn all of this in one sitting.
Q: How do you eat an elephant? A: One bite at a time.
Please feel free to contribute to the Insulin Pumpers Webpage in
whatever way you can. Any help at all will be greatly appreciated.
If you aren't comfortable with all the "computerese", that's OK.
Someone will help you. The main thing that the site needs are people
who are willing to write FAQ's and HowTo's. We can't stress enough
that without people who are willing to write, there will be nothing to
put onto the site! Someone will help you with the SGML markup and
document transfer procedures if you need it. Just ask.
By developing the Insulin Pumpers Website, you will be helping to
spread the good news about pumping to people with diabetes and
concerned healthcare professionals. Education is the key to success.
Find a topic you are interested in writing about and GO FOR IT!
8. Copyright Notice
Copyright (C) 1998, Insulin Pumpers , Bob Burnett
bburnett@twcny.rr.com , and Mary Jean
Renstrom Mjrenstrom@aol.com .
Permission to use, copy, distribute this document for any
purpose is hereby granted, provided that the author's / edi-
tor's name and this notice appear in all copies and/or sup-
porting documents; and that an unmodified version of this
document is made freely available. This document is dis-
tributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY, either expressed or implied. While every effort
has been taken to ensure the accuracy of the information
documented herein, the author / editor / maintainer assumes
NO RESPONSIBILITY for any errors, or for any damages, direct
or consequential, as a result of the use of the information
documented herein.