Several months ago, I left my previous position and my goal before leaving was to leave as much good documentation as possible. While there, I had somehow ended up carving a little niche in terms of tasks that I’ve taken on, and I wanted to leave behind what I could. I hope I succeeded, but only time will tell. I wish I had dedicated more time to this type of task prior to leaving it all for the end. It had always been on my never-ending to-do list of things I would really like to finish eventually. But I think that the summer is probably a good time to get started on creating documentation or to start updating existing ones, and maybe these tips might help others who are also trying their best to document. Here are some lessons that I’ve learned or that I wish I learned before I began.
1. Write It Out As You Work
This is a lesson I wish I learned and internalized much earlier, and while it’s fairly obvious, I think it can be easy to ignore. But it’s really the case that when you write up steps as you are completing said steps, the rest of the documentation becomes much easier. You’ll be less prone to forgetting how you do something or small steps that may be obvious to you, but not to others.
For example, I had created documentation on how to request copies from the copyroom. In retrospect, there are a lot of steps that I forgot to include, which I should have but it didn’t occur to me at the time. But one step I probably should have added is a reminder to send documents as PDFs instead of other file types–this was obvious to me because I had worked with the copyroom previously and they had mentioned to me that they highly prefer PDFs. But it is not inherently obvious that all files should be sent as a PDF. And this leads into my second lesson:
2. Don’t Assume
When you assume, the donkey becomes you, or so the saying goes. But writing things out step-by-step and explaining why such steps are necessary is not only helpful for explaining how the work should be done, but it’s also a good exercise in reviewing whether or not those steps are still necessary or are just past practices that stuck for the sake of tradition.
There are some easy and practical ways to do this. One is to make sure that you write out terms/phrases before using any abbreviations. And too many abbreviations end up making alphabet soup, so if it doesn’t take too much effort to write it out, I would just write it out. Another way is to accompany the documentation with relevant images that clearly show what you’re working on. The documentation shouldn’t be only made up of images, as text should be there to explain everything else. But, for example, not everyone may be familiar with a database interface, so it can be helpful to screenshot where the menu button can be found, and so on.
Image by Randall Munroe xkcd.com licensed under CC BY-NC 2.5
3. Keep It Consistent
Try to ensure that your documentations follow a specific naming convention and formatting standards. And if you are trying to keep documentation within your department or team, try to keep it consistent across the board. This is so that it can be easier to find the information you’re looking for, and also it can provide a roadmap for others to create their own documentation, as they now have templates they can use.
One downside of this is that once you decide on a format, you may end up married to it, until the next time you can undertake a documentation project. So perhaps take some time in designing the “ideal” format or look at other organizations’ documentation, before deciding on one.
4. Set A Schedule
In addition to creating it as you work, setting aside dedicated time to creating and updating your documentation can make the process move more smoothly. This will also ensure that your documentation is up-to-date. It can be frustrating to find documentation that would help answer your problem, but only to see that it’s several years out-of-date. Setting a manageable and realistic schedule for updating will hopefully avoid that problem.
RIPS Law Librarian Blog 