Development Documentation

Pexels / Pixabay

As developers, it’s part of our job to code and design aspects of an ask. A prototype, a full application, a module for another developer, and more. While doing this, it’s easy to forget what transpired last week that caused changes (unless you have a scrum master). Someone might have questions about certain aspects of the design, the progress of development, or more. That could go back a day or a week or a month or even a year.

A Personal Wiki

Since my memory isn’t equipped to facilitate an accurate and quick answer to something like that, what I do is document my own activity as best I can in a wiki that runs on my laptop. I run this on my own laptop because I wanted complete creative control in how things are presented. I can code aspects into it, adjust the CSS for elements, etc. A presentation is important to me and anyone who might later consume this material – including myself.

I chose the open-sourced DokuWiki for the system that I run.

I have access to all the code, it’s updated fairly regularly, there are extensions that I can quickly add for enhanced functionality, and it uses a flat file system (i.e. no database to worry about). It’s quick. It’s available to those on our work LAN – so I don’t need to worry about having it hang out on a public server and worry about accounts/passwords. Anyone within our network (or who has VPN access) is free to view my wiki if they know the local URL to it. They are free to edit pages as well – in case I’m working on a project with others and they want to contribute as well.

If someone asks for information, I can quickly shoot them an email linking to my wiki. The way I set things up is like so…

My wiki home page contains links to my projects/documentation. Each wiki page I have is its own project. Each wiki page has a main header with associated internal billing code – and each day is a segment of that page. So things exist in chronological order. I have a timeline menu on the right side, so you can see the headlines and jump directly to one of them. Each page can be as graphically rich as I would like. I can insert video, audio, images, slideshows, etc. The wiki is beautiful – and far superior to Mac OS X’s Server implementation. If I spend the time, I can do whatever I want. It looks nothing like Wikipedia.

Bear

BearWhile I sometimes author posts (daily segments) inside the wiki itself, I’ll also often use Bear, a note taking application. This application allows for a very clean and open text entry mode which frees my mind up a bit. I can use tags to set up filtering – which mirrors the dates and categories in my wiki. A great feature of Bear is that the text that I author (rich text mind you) can be copied as markup. Then I can paste into my wiki, and the markup matches fairly well with what my wiki expects. After a little editing, I have a piece of fully marked up text.

You can find Bear in the App Store. I currently use the free version of it since I’m not worried about the premium features.

Conclusion

Please consider using such a setup for documenting your progress. Even if no one else will need to view the stuff, it’s a great resource for yourself when you’d like to access previous learning for projects as they pop up. It only takes about 30 minutes a day, and once you set up the wiki as you want it to look, it becomes easy to author content that is both useful and beautiful. It’s impressive to managers as well. If you take your work seriously, you really need to do this.

Leave a Reply

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

Time limit is exhausted. Please reload CAPTCHA.

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