Writing Documentation – Step One, The Basics

This is the first in a series of posts related to writing documentation. Click the category tag on this post to see them all.

Full disclosure: I was once a high school English teacher. Now I am a librarian. Writing, research, and writing about research are THINGS with me.

Documentation is all about writing. You’re writing what you learned about the Thing you did, both from a research and an execution standpoint. It’s a way to share more than just the finished item. You’re sharing the entire project journey through your documentation.

When you’re writing documentation, try to write in a clear, accessible style – imagine that you are explaining the Thing you did to someone who knows next to nothing about the Thing. For example, when I was writing my documentation on Han Dynasty silk shoes, I talked about the history of silk in China – and I cited my sources. I didn’t go into a lot of detail, because there have been entire books written about the history of Chinese silkworm cultivation and silk production, but I made sure that if the reader wanted to, they had a place to go to learn more.

And that’s the thing – make it easy on your reader. Organize your documentation so that it flows, and proof-read it for mistakes that snag the eye or cause confusion. Treat it like you’re going to publish the finished product – either as a blog post, academic paper, or some other online or print resource.

Even if your project isn’t the be-all and end-all version of something, treat it like a hundred people are going to look at it as a potential reference for their own project. Honestly? This is one of the reasons why I love the SCAdian Internet. If I’m starting out on a new project journey, one of my first steps is to see if someone else has already blazed a trail. I can learn from that person – what worked, what didn’t work, and what resources were helpful to them. Don’t feel like you have to reinvent the wheel.

Back when I was in college, I had a little spiral bound book that was a Sacred Text for all English majors – The Beacon Handbook. It’s a great little book that is easy to use and answers pretty much any question you may have about:

  • writing mechanics;
  • style; and,
  • format.

The Beacon is what taught me that it is a Right and Proper Thing to put semicolons at the end of items in a bulleted list that are part of a sentence, along with the ” and,” before the last item.

But the Beacon isn’t the only writing guide out there – find one that you like. Look for writing guides at your local library. Ask your favorite English Teacher friend for their recommendations. Browse the bookstore’s offerings.

The last piece of basic advice I can give is to write about your project from the start. Keep an A&S journal. This can be a physical notebook, a blog, or even a series of posts on social media. You’ll be thankful for this record of your process, pictures you took and shared, resources you looked at, and notes you took when it comes to writing your formal documentation.

I’ll leave you with a tease of future links to the rest of the blog posts in this series:

Writing Documentation – Step Two, The Research

Writing Documentation – Step Three, The Execution

Writing Documentation – Step Four, The Writing

Want to share this?

4 thoughts on “Writing Documentation – Step One, The Basics”

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.