Documentation

From MiddleWiki

Jump to: navigation, search

While the main purpose of Documentation in the Middle Kingdom is for A&S Competitions, there is nothing precluding documenting and researching just for the joy of it.

Reasons to write documentation:

  • Requirement for an A&S Faire or Competition
  • Personal notes so that you can do this project again!
  • Developing class notes so you can teach this in the future

In general the term documentation can refer to evidence, research or sources. For example "Is there documentation for that hair style in the fourteenth century?"

Documentation is usually a written report on your A&S Competition item or project you have created (or performed). It can also refer to less formal notes and references.

A guide to 'levels' of documentation requirements you may see at various A&S Competitions (note: these are not official classifications, just given to be helpful, thank you to Master Randthulfr for this list.):

LEVEL 1 -Display level: Simply provide Entrant's name, Item title description, When the original was made (performed), Medium of the Original, Medium of the entry, Time of the Original, Place of the Original.

LEVEL 2 -Simple Event A&S: Same as above, adding brief discussion of the meaning and historical context and citing at least one reference by either the collection it is housed in or a book, etc. from which it was shown.

LEVEL 3 -Middle Kingdom A&S Event Entry: See MK A&S rules & criteria and http://middlewiki.midrealm.org/index.php/Documentation

LEVEL 4 -Advanced: Same as 3, but add in-depth discussion of related context, material and/or style choices.

Contents

Basic Documentation

Basic documentation is easy, remember if you scribble "Widget based on a early 16th century woodcut by Albrecht Durer" on a 3X5 card and place it next to your widget you just went from zero points for Documentation to one point! Getting a better score takes a little work, but it's not as scary as you might think. You can think about Documentation as a conversation with the judge about your entry. If someone came up to you at an event and said "Wow, that's cool! How'd you make it?" You would likely launch into a long, excited conversation about your inspiration and the pitfalls and successes you had making it... just put that onto paper!

Try to answer the questions:

   Who
   What
   Where
   When
   Why
   and How 

These are frequently the same questions you had in mind when you first decided to do this project. Another way to look at Documentation is simply writing down your research.

Always make sure that your documentation is well organized and easy to read; frequently Judges will have a very limited amount of time to read your documentation and may miss important citations and sources if your documentation is poorly organized.

In your documentation, you may want to discuss your own analysis of the finished item. Discuss the creation process, areas of improvement, and what you learned from creating this item.

You will be expected to supply support of your choices in creating your project and your understanding of the creation process of period items like yours, how yours differs from period samples, and your design and thought processes to achieve the results you got.

You will also be expected to supply a Bibliography of books and scholarly sources to back up your work, as well as any footnoted points of interest the A&S Judges should know.

First time entrants are highly encouraged to seek out a minister of arts & sciences as well as Laurels or Apprentices and other artsy folks who are more familiar with the process to help you write what you need correctly.

Documentation for people who hate to write Documentation

By Milesent Vibert, OL (Grace Vibbert) grace@case.edu

What is Documentation anyway?

You just made something cool and a friend compliments you on it at an SCA event and asks you where you got the idea or information on how to do it and you chatter excitedly for a good hour about your project… well that is documentation, only spoken. It can be less scary when you think of documentation as just a conversation on paper. And on paper you can be more organized and not forget the really cool parts.

Your documentation tells people how awesome the thing is. Some coolness is obvious, but most truly nifty SCA projects you need some background information to understand just how cool it is. That’s where Documentation comes in.

Good Documentation answers all the questions people want answered clearly and concisely; obviously you’ll never have *perfect* documentation because you don’t know who your audience is going to be. But you usually know what the major questions are going to be because they were the same questions in your mind when you started the project.

Why should I write Documentation?

For most folks the answer is “Because it was required by this competition…” But that’s not the only reason to write Documentation! Write it for yourself! By keeping a working Documentation document you have a reference to go back to if you want to do this project again or if someone asks you a question about it. Your memory is not so great. Trust me on this one. You aren’t going to remember why you did what you did if you don’t write it down. Sure some stuff we remember, but others (usually important details) we won’t .

Documentation prevents mistakes! We’d all rather do the job right the first time, right? Rather than spend hours (or years!) on a project and then find out we used the wrong material or technique after the fact. Oops.

Documentation is also great for those invariable differences of opinion

Documentation can be easily turned into a class handout if you decide later down the road that you want to teach someone else how to make or perform this thing.

Getting Started

Unfortunately, most people don’t think about documentation until after they’ve finished making something and want to enter it in a faire or competition that requires documentation. It is a lot harder to document after the fact. Make it easier on you and more useful and start the documentation before you start making your project. It’s easier to write things down as you find them than to go hunting for that book you saw that one picture in… wait, was that from the library or did I borrow it from Mistress Bookworm? It had a blue cover… yeah. Not fun. Another word for documentation? Research.

Most of the time your project started with some inspiration; a painting you saw in a museum, or an artifact someone published on-line or a project done by someone else in the SCA. Start your documentation there. “My inspiration for this project was…” Then think of the questions you had to answer for yourself before you made your project; what am I going to make this out of? How am I going to join these two pieces together ? etc. Write those questions down. This will help you build an outline.

Another secret: you don’t have to write your documentation in the order it is read! You can start with the end, middle, wherever. Remember, it doesn’t have to be perfect!

Big secret; documents can be edited. *gasp!* You aren’t chiseling this into stone. Most of us aren’t even writing it on paper. You can always add more or subtract. When I start researching a project I start a word document and I put everything I find in there or in a folder together. This is going to include a lot of stuff I end up not needing in the end; like pictures of three different sleeve varieties. Once I pick which of the three I’m using for my dress, I can delete the other two from the documentation or move it to an appendix if I think it’s interesting or appropriate enough to keep.

The first draft of your documentation is going to be ugly. It just is. But it is still better than no documentation and lays a foundation you can work with.

The Recipe

A Laurel at Pennsic a few years ago was handing out “Documentation Recipe cards” which was a brilliant idea, little three by five cards with the recipe. If I find them I’ll have to make copies for this class! Here is her recipe to the best of my memory, with probably some additions:

  1. What is it?
    • When? (Time period)
    • Where? (country or region)
    • Who would’ve done this or worn/used this?
    • What was the function of this object/performance/garment?
    • This entire section can usually be summed up in one sentence “A 12th century Noble Woman’s Dress from Northern France” which can also be used as a title for your document.
  2. What materials did I use to make it?
    • How did what I used differ from what a historic craftsman would’ve done?
    • Why did I choose these materials?
  3. How did I make it?
    • How did what I did differ from what a historic craftsman would’ve done?
    • Why did I do it that way?
  4. Repeat steps 2 and 3 as many times as necessary to cover all the unique components of your project.
  5. List sources

Once you’ve filled out the outline, go back and write things out in complete sentences, remembering to cite where you got information. It doesn’t matter how you cite, pick the method that works best for you. I like footnotes because they’re pretty easy to do in Word. But just saying “According to the book by Smith on page 34” or (Smith, p.34), etc. works just fine. The question most people forget to answer in their documentation is “Why,” and in my experience, that is the one the Laurels are usually most interested in!

“Putting Lipstick on the Pig”

Once you’ve got your basic, rough documentation done, take it to a friend, especially one who knows nothing about your project and ask them to read it. Frequently someone who is very familiar with a project will fill in gaps in the document without realizing it. It’s good to get fresh eyes on the document!

Again, don’t stress out too much about using correct citation formats and such, that doesn’t matter as much as being readable (Unless you are entering the Research Paper competition!) and be consistent.

If you can, include pictures. You can’t guarantee that someone will read every word of your documentation, but they will probably look at every picture. Trim out things that you don’t need, keeping the documentation short and organized makes it more likely that it’ll actually be read and understood.

If you have time, have your local grammarian check your documentation for spelling and punctuation errors. You don’t want grammar errors to distract the reader from how cool your project is.

Where to get more help

If you want to move from writing Documentation to writing GREAT Documentation I’ve got another class on that (see below). ? Check out your local A&S Faire staff for tips as well. Remember that if you are writing documentation for the Kingdom A&S faire you have a little bit of an advantage in that you know the questions the judges will ask because you can look at the judging criteria so you can tailor your documentation to the audience. Former faire staff and former winners also have insight and will probably be only too glad to share!

Ask a Laurel; not every Laurel is great at documentation, but pretty much every Laurel will know someone who is that they can point you to for help. ?

What separates ordinary documentation from extraordinary documentation is the content in it, not the order of paragraphs or turn of phrase. If you want the best documentation, use the best sources available to you and think critically about what you are making and how. Roll up your lab coat sleeves and dive into mad science!

Writing Good Documentation

Advice from Milesent Vibert (OL): Note: This is on writing *Good* Documentation and therefore the advice is a bit excessive if you're just looking for some very basic documentation. In other words: You don't have to follow all of this advice!

The Golden Rules

  1. Start your documentation before your entry is done
  2. Know your sources, and use a lot of them
  3. Any time you make a statement, back it up
  4. Beware common knowledge
  5. Know your audience
  6. Be concise - avoid rambling and personal anecdotes
  7. Be organized - make the documentation easy to read quickly

Start your documentation before your entry is done.

Trust me on this one, it's a LOT easier to document as you go than to "Backwards" document. You will learn things while you are writing your documentation that will affect how you want to make your entry, if the entry is already made it will be too late to make changes. Also writing as you go means that you're less likely to forget something, like which book you found that useful tidbit of information in. Usually I will start writing my documentation before I even buy materials for a project.

Know your sources, and use a lot of them

This is a common stumbling block for entrants as well as judges!

Use good sources. Sometimes there are no primary sources available, that's fine and a part of what we do, but use the best source you do have available.

The best research will use as many sources, and types of sources (books, written descriptions, photographs, articles, viewing objects in a museum, etc.) as possible to get a more well-rounded idea of the subject and also if five books by different authors say it was this way, you can feel more confident that it really is so than if it is only listed in one book.

Your source's source is NOT your source. It can be tempting to open up that scholarly book and say "Hey! This guy's already done all the research for me! Keen!" because the author's listed a lot of good primary and secondary sources in his bibliography. Don't be fooled! You did not consult those primary and secondary sources; you only consulted what the author said about them. And that author is human and could be mistaken.

(Note: You don't always have to re-invent the wheel, and for normal documentation it's not necessary, but GOOD documentation thinks critically.)


Any time you make a statement, back it up.

It can be easy to make general statements based on what you learned in your research, but you forgot to write down what book you found that in. This is a bad practice, if you don't back up statements with a citation, the judge doesn't know you did that research and aren't just repeating common knowledge. For example "In the Middle East at this time illumination was done on paper, not parchment (See Bloom, page 67)"

How you back it up is up to you, parenthetical references (like the example above), footnotes, endnotes or direct quotes. Whatever works best for you; there is no one way to make a citation. (But please do just pick one form.)

Beware Common Knowledge!

Things that "Everyone knows" can trip you up in several ways. First, if you rely on it you may find to your embarrassment that there may be no actual source to back up the statement. Secondly, you can run into trouble if you assume your judge knows something because it is common knowledge; the judge may not be as versed in your art as you are! Thirdly, the judge may believe in a particular incorrect Urban Legend and you will need to make a statement to counter-act the potential argument. "In the SCA it is common belief that these hats were stuffed with straw, however I was unable to find any source other than a modern 1960s satire which mentions straw in conjunction with these hats."

Know your audience

Or rather remember that you don't know your audience! An A&S judge can be any member of the SCA, they are a volunteer who may be judging something they didn't want to (for example a weaver roped into judging costuming or an illuminator judging pottery). Keep your language professional and polite, avoid jargon.

This could also be titled "Read the criteria." This is what the judge is reading; look at it to get an idea of what questions the judge will be looking to answer. It is a good exercise after your first draft is done of your documentation to go back to the criteria and check your documentation paper against it. Do not just copy the criteria into your packet; some people recommend it but I think it's tacky and a little insulting to the judges who have the criteria in front of them already.

In general it is a faux pas to include your name or contact info on your documentation unless you are having face-to-face judging.

Be Concise

Frequently an A&S judge will have very little time to judge your entry, they won't have time to read it carefully and will likely skim to find what they need. For this reason it's important to make every page count and not take up space with anything unimportant. Leave out personal anecdotes unless they really add to your documentation; it's great that you've been in love with nalbinding since you were a little girl, but does the judge really need to know that?

Tables and charts can help show a large amount of documentation in a small space.

A picture really is worth 1,000 words sometimes. A judge can look at a picture and compare it to your entry easier than reading a description. Especially when pictures are your source! Also, you can't guarantee that the judge will read every word you write; but the odds are good that they will look at every picture. (Don't include pictures that do not help you!)

Be Organized

By having clear sections, it will be easier for the judge to find what they are looking for in your documentation packet. Have section headings (or even tabs, I've used post-it tab markers effectively on very large documentation packets to help make it easier to flip to different sections.)

There is no one right way to organize your documentation, and frequently different types of entries will work better with different organization. This is just my opinion on a good way to organize a documentation packet.

  1. Title and description.

    Have a title for your entry and start with a statement about what you are trying to achieve. Are you re-creating an exact object or making something new "in the style of"? What country is it from? When? How would it be used and by what class of people? What aspect of the piece were you most concerned with?
    Now you have a choice to make. If your entry consists of several different parts (such as an outfit made up of different layers of clothing) you may want to break your documentation packet into sections for each piece, for each section list the sources and evidence and construction and materials separately.

  2. Sources and Evidence

    List your evidence and explain why you chose the sources you did and what conclusions you drew from them. For example starting with a statement like: "There are no extant garments of this type, so I relied heavily on artwork and written records as well as looking at some of the extant garments of nearby countries." Then following with what you learned from each of these sources. "Most of the images of young men I examined (25 out of 31 images) showed a left-opening lapel like the one pictured to the right."

  3. Construction and materials

    Then go into detail about how you made your entry; what decisions did you make along the process and why? What materials did you use? How did you use them?
    Always mention where you learned something new or had to improvise along the way.

  4. Appendix

    If you have other evidence to present, an appendix can be a very useful way to keep your paper concise. For example a table listing pigments used at the time or fabrics found in various sources. If you include an appendix, remember to reference it in the body of your paper.

  5. Bibliography

    Finally, end with a bibliography. There are some choices when making your bibliography as well. You can list just your major sources or only sources you cited in the paper, or you can list all the sources you consulted. The last option is best as it shows honestly what you looked at, though you may want to go with one of the earlier choices for brevity's sake and title the section "Selected Bibliography" or "Works Cited" so that the reader knows that you consulted other sources not listed.
    It is okay to cite web sites, even scholarly journals are now accepting web citations. The bibliography entry should look like a journal article, and always include the date you viewed the web page (as web content can change). I like to include a few words about the site as well such as "French museum web page" or "Interactive on-line exhibit."
Personal tools