Contributing to Josh's Linux Guide
Created on July 9, 1998
Last updated August 28, 1998
Development stage: Alpha
If you feel that you would like to contribute to this Linux guide, I
encourage it, since I can't handle everything. More advanced topics are
also welcome, since people who are new to Linux eventually move on. I'd
like to keep the audience reading as long as possible. There are just some
things that I want to get across, to ensure that it works out well.
- You must be willing to maintain your document, and this means that you
must provide an e-mail address to contact you with. You must also be
willing to receive any sort of feedback from readers, and even help them
with any problems they encounter.
- Have a short title on your pages, but let them be descriptive enough
to let the reader know what the page is about. I've made this mistake
plenty of times. Put your title in the <TITLE> and <H2>
tags.
- Don't use abbreviated Internet English. Use proper spelling and
grammar as far as you can help it. There will be typos, but eliminate them
to the best of your ability.
- Have fields for when the page was created ("Created on"),
when it was last updated ("Last updated"), and its development
stage ("Development stage" can be alpha, beta, or complete). You
can see examples of this in many of my documents.
- Have a white background (#FFFFFF) and black text (#000000) on your
documents. Yes, submissions have to be in HTML. Or even SGML. Nothing
else.
- Though it's not necessary, I highly recommend allowing people to copy,
print, and re-distribute your documents. I also let people modify my
documents, but they have to give credit to me. I'm no legal expert so I
don't know much of the quirks involved in putting up documentation online.
You may also put your work under the OpenContent if you want. I am also considering switching
to OpenContent. Put your copyright notice at the bottom.
- If it's not too inconvenient, have the page hosted on your own web
space so that you can easily make updates to it. If that's not possible,
then just e-mail me the updates, to jgo@local.net. Even if you have the page
hosted on your own server, it's also a good idea to e-mail me the updates
in case something happens or whatnot. It will be copied into a
subdirectory called submissions/.
- Filenames depend on what type of audience it was aimed for. If it
begins with "linux-" then it should aim to be applicable to any
and all distributions of Linux. If it begins with "redhat-" then
it should be limited to the Red Hat distribution. It's better to write
documents aimed at all distributions. I only have the "redhat-"
pages there so people can install it, since the way distributions are
installed varies greatly.
- Put commands in Bold (<B>), directory and file locations in
fixed width (<TT>), and make printouts preformatted (<PRE>).
Remember to close the HTML tags. These are just basic guidelines to
follow; you can also use italic.
- Subsections should be in <H3> and sub-subsections should be
<H4>. You should never have to use <H5>.
- Links to any outside sites must have a target of "_top" in
order to ensure that they aren't loaded in the frames. I emphasize this
strongly so that your readers don't get annoyed at you.
- If there's anything you're still unsure of, look at the HTML source on
any of my documents. If you still aren't sure, then send me an
e-mail.
Following these guidelines will help tremendously in keeping things
consistent. Any future changes that are required, I'll let you know, or
I'll make the change myself.
On a side note, I think we need more "Informational"
pages. The "Instructional" section is getting a wee bit
crowded.
Copyright © 1997-1999 Joshua Go (jtg@computers.iwz.com). All
rights reserved. Permission to use, distribute, and copy this document is
hereby granted. You may modify this document as long as credit to me is
given.