{"id":257,"date":"2016-01-29T09:27:22","date_gmt":"2016-01-29T15:27:22","guid":{"rendered":"http:\/\/biblionalia.info\/leah\/?p=257"},"modified":"2016-09-25T17:50:55","modified_gmt":"2016-09-25T22:50:55","slug":"writing-documentation-step-one-the-basics","status":"publish","type":"post","link":"http:\/\/www.biblionalia.info\/leah\/blog\/2016\/01\/29\/writing-documentation-step-one-the-basics\/","title":{"rendered":"Writing Documentation \u2013 Step One, The Basics"},"content":{"rendered":"

This is the first in a series of posts related to writing documentation. Click the category tag on this post to see them all.<\/p>\n

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.<\/p>\n

Documentation is all about writing. You\u2019re writing what you learned about the Thing you did, both from a research and an execution standpoint. It\u2019s a way to share more than just the finished item. You\u2019re sharing the entire project journey through your documentation.<\/p>\n

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<\/a>, 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.<\/p>\n

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.<\/p>\n

Even if your project isn\u2019t 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\u2019m 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 \u2013 what worked, what didn\u2019t work, and what resources were helpful to them. Don\u2019t feel like you have to reinvent the wheel.<\/p>\n

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<\/a>. It’s a great little book that is easy to use and answers pretty much any question you may have about:<\/p>\n