Richard,
> I am starting my three How-to's this week.
Excellent! All three would be quite useful.
> Is there a template that states where to "Drop in" the required info. Sort
> of a high school like, Hypothesis, Apparatus, method like thing? :)
Well... I did put an (SGML) template up online at:
http://www.e-smith.org/docs/template-howto.sgml
but if you're not writing in SGML, it is not overly useful
Especially since I didn't really flesh that template out with things that
you should have inside of your document. I'll do that sometime
this week and get the information up there. I'll also put up a
page describing what we are looking for in a HOWTO. Thanks for
the prompting.
In the meantime, there are a few basic things that I look for in
each HOWTO (obviously, the applicability of some of the sections
I mention will vary depending upon what you are writing about):
- a statement right at the top of the document about which version(s)
of the e-smith server the procedure has been tested on (and
perhaps a statement that it "should" work on earlier versions,
or that it will NOT work if that is known). Something like:
This procedure has been tested with e-smith server 4.1.2.
It should also work with versions 4.1 and 4.1.1, but has
not been specifically tested on those systems.
- some kind of introduction as to what this HOWTO is about. What
does it (the software/service/command described) do? Why would
someone want to install it? What problem does it solve? This
might just be one sentence or a paragraph. It might be a couple
of paragraphs (depends how descriptive you are
- if the HOWTO is about software, a section on downloading that
includes links to the relevant files and includes a list of
dependencies, if any, with links to where to get them
- an installation section that walks people through the steps
involved with installing the software
- a section on "using" whatever it is you are describing. It
could be as simple as saying that there is now a new web panel
where you can modify the information.
- if possible, a section on "uninstalling" the software would
be useful, too, in case people want to undo what they have done.
- somewhere in there, links to any other known resources such
as home pages of the web site of the software program
Like I said, not all of these are applicable to every HOWTO, but those are the
general type of things that are useful. In most cases, the installation and
usage (or configuration) are probably the most important. The
"uninstalling" section can be added later.
As far as examples... one that I wrote that has many of the things
I look for is the NIS HOWTO at:
http://www.e-smith.org/docs/howto/nis-howto.html
Note that I put the downloading instructions at the beginning of
the Installation section. (If you want to see the SGML for this, it
is at http://www.e-smith.org/docs/howto/nis-howto.sgml )
If you have more questions, please let me know.
Regards,
Dan
--
Dan York, Director of Training [EMAIL PROTECTED]
Ph: +1-613-751-4401 Mobile: +1-613-263-4312 Fax: +1-613-564-7739
e-smith, inc. 150 Metcalfe St., Suite 1500, Ottawa,ON K2P 1P1 Canada
http://www.e-smith.com/ open source, open mind
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
