[Ansteorra] The Journey: A&S

[Marc Carlson]

>From: "cehuse" <cehuse at sbcglobal.net>
>So, this leads me to ask....What makes for good documentation? How do >you
>write documentation? I've not entered anything because I know nothing about
>writing documentation. When I have asked, the only answers I get are vague
>and confusing.
>Maria

It's been a few months since I looked at any judging forms, but if memory
serves, the tried and true should still work just fine.  That is, at a
minimum, you might try answering the questions: who, what, why,  when, and
how.  Who are you, what is it, why did you do it this way, when is it from
(even if it's something blatantly modern, say that), and how did you do it?
  And try to be clear about what you are talking about.  You can get a LOT
more detailed than that, but that's always a good start.  Really,
documentation should be the EASIEST part of your work.

It's a tough question, since the last I heard there were no absolute
standards or quidelines to work from.  And, come to think of it, that's
probably a good thing.  I know that while -I- think writing's fun, I know
that's not the case for everyone (not everyone thinks that Research is a fun
way to pass time either).  A lot of people suffer from what I jokingly refer
to as understandable fear from having been mauled in some high school term
paper writing incident.  This tends to make them shy away from writing --
and if they thought that people were going to judge them on their writing,
they'd be even more reluctant to do it.

Your email question seemed clear and understandable.  You shouldn't have any
problem with your documentation.

=====

Now if you want to move up in complexity, perhaps as you get more
comfortable with it, you will want to include where you got your
information.  Some people I know can get a bit stuffy about the use of
particular manuals of style although I have yet to be convinced that for
people who are not writing research papers, they are actually necessary.
Just be consistant in your usages.   As an aside, Manuals of style are, for
anyone who doesn't know, are books of instruction about the mechanics of how
to make a paper and references look standard and professional.   There are a
number of them -- Most people are familiar with the MLA style sheet, which
is the baby brother of the MLA Style Manual.  Some people (especially those
in the sciences) like APA.  I prefer an abbreviated Turabian myself, which
is a variation of the Chicago Manual of Style.  There are others including
local "in house" versions.

For doing this kind of source citation, you are going to want to note
author, title, when and where it was published and by whom.  If you quote
directly from a source, cite that.  Again, just be clear and consistant.
All these style manuals are mutually incompatible and the worst thing you
are going to run into is a judge who prefers one  style over the other.
Personally, I think that if you go to the effort to put the date of
publication in the same place on each line, they can make the effort to look
someplace else in the line than they are used to.

When you are used to that, you can start making the documentation into more
of a research paper.  Tell things in more detail, that sort of thing.  If
you decide to go to this extent, have other people read your paper, to check
and make sure it makes sense to them, that you aren't leaving anything vital
out.  Try not to get your feelings hurt if they find things wrong in like
your paper -- one of the trickiest things to learn is that you really WANT
them to point out errors.  You need the practice to get better.  At this
point you might want to start looking into a basic style manual, as a tool
to make things easier for you (less for you to think about), but not until
you are comfortable.

If you continue down this road, you can even reach the point that the
documentation becomes the critical part of the entry, and anything else you
submit is just ancillary to that - but at that point, you are submitting the
research paper as the primary entry.  If you choose to stop before you reach
that point, that's great too.

In short, start small and simple, one project at a time, one competition at
a time.  Each time see if you can produce better, or more complete
documentation.  The judges may or may not tell you if they want more
information (some like to give feedback, others don't - try to not take it
personally either way).

Good luck with it.

Marc/Diarmaid

_________________________________________________________________
MSN Photos is the easiest way to share and print your photos:
http://photos.msn.com/support/worldwide.aspx