Dos of Documentation
Things To Keep In Mind For Your Next Project
Documentation can seem like the less attractive part of what we do on a day-to-day basis, but it still stands as one of the most important part of our process as good developers.
When I was still in college, I got my first internship opportunity in the states at an HR Information Systems company that implemented Software as a Service. I was brought on as a Technical Writer and I worked between the IT and marketing departments. My main responsibility was translating the technical terms and concepts that came from the development teams into digestible forms of information to be used for the entire company as well as marketing collateral for external sources.
Thinking back on this sparked the idea to talk a little about my experiences in documentation and some thing I’ve learned that helped me a better developer and communicator that I am today.
Anything Can Be Documentation.
Documentation comes in a bunch of different shapes and sizes. Everything from functions that we’ve implemented, screenshots of widgets we’ve used and a library of links other useful resources across the net. If it communicates what you are trying to get across effectively, why not use it? Just make sure it’s in an appropriate format for your readers/viewers.
Sketch It Out.
I’m not the fanciest illustrator in the world, but I find when I’m sketching out a thought on how to approach something, I usually come out with a neat drawing that encompasses the idea fairly well at the time. You don’t need the fancy software like Visio or Illustrator to give your rough ideas form. Sketching what you think the concept looks like in your mind will help you translate it into something more refined later.
As You Think It, Write It.
I do a lot of full-stack work, so I’m constantly moving in between front-end, back-end and design work every time I switch gears. In the early concept and documentation phases, this can help you build your thoughts as your mind jumps from one aspect of the project to the next. Think of it as a more of a ‘controlled brainstorming’ that you will actually capture to use again in the near future. I get a lot of use from these thoughts by using Markdown files to create the project wiki while I’m inside the text editor. The important thing to remember is to clean up your thoughts as you go along.
Include What’s Needed AND Necessary.
Some times you might get in a situation where you wish you had your hands on something you mentioned before, but for some reason can’t find. In case something blows up in your face, documentation provides awesome coverage.
To avoid some of the unpleasantries, if you come across an idea or requirement that you have a gut feeling you should keep somewhere, then capture that thought immediately. If it’s a client-facing thought, make sure it’s communicated as soon as possible.
“If It’s Not Documented, It’s Not Done.”
One of my best friends, who is also a CPA told me this one day and it has stuck with me ever since. When you hand over and deploy a project for it’s completion, more than likely you will have to provide your client with some instructions or guidelines on what you have built for them.
A lot of developers I’ve talk to find it easy to get into the habit of only documenting after the project is done. I took documentation more seriously the first time I got on a huge project that I knew had to be turned over with extensive instructions. Start earlier for less headache down the line.
Wrapping Up
Starting out as a technical writer was a great foundation for me now looking back at it. Today I find myself still using most of the techniques I’ve picked up since then to communicate efficiently with my team and clients.
