Why You Should Document Your Project
I write this from the perspective of a maker. When I say project, I mean hardware project, and when I say writing I mean non-fiction writing.
Motivation
I have learned much from the work of others. And much of that learning came about because those people put in the effort to document their work on the internet. Unfortunately, a large fraction of makers do not take the time to write up their projects. This is a big loss for not only the makers themselves, but also the community at large that could have benefited from their work. In this article, I attempt to make the case for documentation by discussing how it could be benefitial, and also look at some of the common obstacles towards achieving that goal. I also offer some practical suggestions on how you can get started with the process.
Why Document your Projects?
Here are the primary reasons I think you should document your projects:
- It helps others.
- It deepens your understanding.
- It opens doors.
- It is your best reference.
Let’s take a brief look at the above points.
It Helps Others
The most obvious reason to document your work is so that it benefits others. Since the maker community is fuelled by the spirit of sharing, it makes sense that you publish your work.
It Deepens your Understanding
If you are like me, then your mind is a cacophony of activity, with thoughts flitting about from one topic to the next. When you try to put this fuzzy cloud down on paper, you will need to make a linear narrative out of it – if you want others to understanding what you’re saying. Fact needs to follow fact in a logical order, and in this process of converting your thoughts to a structured document, you will find that your own understanding of your project has deepened.
It Opens Doors
A long term practitioner of any art will tell you that it’s not a single work that matters, but the body of work you create over a period of time. When you make documentation a habit, you will soon find that you have created a portfolio of projects. This is much more credible than a resume with exagerrated accounts of your fabulous acheivements. In fact your documentation is your real resume. People will eventually notice your work, and it will open doors. This blog for example, has given me international exposure. It has put me touch with the maker community at large, given me oppportinities for collaboration, and played a part in landing my first book contract.
It is Your Best Reference
When you write up a project, it is a note for your future self. Nothing reads better than your own notes on a topic. That is also a good reason to write clear documentation, so you don’t end up cursing yourself in the future. I can’t tell you the number of times I visit my own blog to dig up some obscure project detail I worked on months ago.
Obstacles & Solutions
Here are some of the common obstacles that get in the way of writing up a project:
- Writing is Hard
- Procrastination
- Fear of Criticism
- Lack of Platform Expertise
Let’s look at the above problems and potential solutions.
Writing is Hard
Here is my favorite quote on writing, from American journalist Gene Fowler:
“Writing is easy: All you do is sit staring at a blank sheet of paper until drops of blood form on your forehead.”
Writing is hard, but that’s not reason enough to deter you from this craft. Writing is a skill that can be learned – just like driving a car, or operating a crane. You don’t need to be “born with it” – unless you are aspiring to be the next Shakespeare. But you do need to practise your craft regularly. Don’t expect to get better at writing by whining about how hard it is.
Procrastination
I hear this a lot: “I’ll write up my project after I am done.” No, you won’t. The only way to document a project is to do it along with the project. But how will you get any work done then? The trick it to keep it simple and fast – just use a .txt file and make notes as you work. I don’t shoot photos and videos of project after I am done – I do it continously, knowing that I will use only what works. (It’s also great to have a visual record of your failures and successes.) If you practise this, you will find that when you are done with your project, magically, a skeletal documentation already exists. Now all you need to do it flesh it out and make it presentable.
Fear of Criticism
When you make your work public, you are naturally opening yourself up for criticism. Unfortunately, the anonymity of the web makes people harsher than in real life when it comes to interacting with others. But getting criticised by a knowledgeable person has its benefits – you just need to let your ego down, and listen to what is being said, and how you can use that information to improve your project. Another fact from my experience – the people who express gratitute for your work will far outnumber the detractors. Also think about this – not only did you make something, but you took the time to document it, making it useful for a lot of people. I think you’ve done far better than most of your critics.
Lack of Platform Expertise
Oh, but I don’t have the time/patience/expertise to create a blog or website, you say. Unfortunately, the year is 2015 and your argument holds no water. Due to the easy availability of blogging platforms, you could get going in less than 10 minutes. I will address this issue in more detail in the next section.
How to Document your Project
Hopefully I have now convinced you – or at least made a few chinks on that anti-documentation armour of yours – that you need to write up your projects. Now let me offer some suggestions on how to get started.
- Start a blog today.
- Your blog is your journal.
- Structure your Documentation.
- Read up on writing.
Let me elucidate a bit on the above.
Start a Blog Today
This is the easiest way to start documenting your project, and signing up with WordPress, Tumblr or similar platforms takes only minutes. Another option is to sign up with maker-centric blogging platform like hackaday.io where you can share your projects and hang out with other makers. You can get more elaborate later – buy a domain name, set up your own website, find the perfect theme for your website, etc. But first things first – starting putting up words on the screen.
The Blog is your Journal
Don’t think that you need to complete an elaborate project in order to write something about it. Think of the blog as your project journal. As you make progress with your project, keep updating your blog. You will find that this workflow will actually help you execute your project better. Any non-trivial hardware project has a number of sub-tasks, and if you consider each of these tasks as a blog article, it immediately gives you a set of targets to work on. With each update, you are one step closer to your project goal, boosted with the satisfaction that comes from documenting and sharing your progress.
Structure your Documentation
“Pick a style and stick to it” – this advice works across many domains, including when it comes to structuring your project documentation. Sticking to a consistent presentation of titles, sections, headings, figures, images, captions, references, etc. will not only make your job easier, but will give a more uniform and professional appearance to your website. Your personal style is not something you start with, but something that you discover and refine over a period of time.
Read up on Writing
Writing is a craft, and it can learned, like any other craft. And like any craft, practice makes perfect. The two books on writing that helped me the most are:
- On Writing Well: The Classic Guide to Writing Nonfiction by William Zinsser.
- The Elements of Style by William Strunk Jr. & E. B. White.
Conclusion
Making is fun, but documenting and sharing your project elevates it to the next level. Hopefully I have convinced you that taking this next step is not that hard. Good writing is good writing, no matter what the medium. You don’t need endorsement from a publishing house to put out good content. So go ahead and write up that project, and publish it on the web. You will be doing yourself a favour.
