I have been developing applications over the past 10 years, and I admit I do not have a long term memory, especially not when it comes to remembering a piece of code or technique, I had used in my previous projects. My memory acts alien especially at times when I need to remember a code snippet for the 11th-hour kinda fixes, which I wish I had documented, instead of choosing to be lazy.
It's true hard work never killed anybody, but I figure, why take the chance? ~Ronald Reagan
Many would agree that a good old notebook best serves the purpose, as it can be carried anywhere and requires only a pen/pencil to jot down your notes. However with time, we realize that paper notes becomes almost impossible to maintain (search, store, carry). I have seen some extremely-fond-of-notebook developers use a Livescribe Echo Smartpen which is a smart option, but then not everyone has that pen right?
Here are some tips to keep your developer notes in a more organized manner and make your life easier.
Tip 1:
A blog can be used as a developer’s journal. Blogging is an ultimate tool to keep your programming notes and refer to them later. Almost all popular blogs (like blogger, wordpress etc) give you an option to set up your blog for free, and with the help of plug-ins, you can even save your code snippets with syntax highlighting. Depending on how you configure it, you can choose to keep these notes to yourself or rather share your experiences with thousands of developers across the world and receive feedback on it (and also earn some extra money).
I speak out of experience. Blogging may look like a tedious thing to do initially, but once you get into the habit of recording notes in your blog, it does wonders for you later. This blog DevCurry.com is one and a half years old and there are over 600 posts here, all containing bits and pieces of our experiences, which have helped us and hundreds and thousands of developers as a reference, and will continue to do so.
Tip 2:
If you want to save only random bits of code, use an online tool called Snipplr . Snipplr lets you store your code at one place and you can share access to your code with other guys/gals at work. Another tool is Snipt where you can share your collection of frequently used commands or code snippets. If you are a Visual Studio developer, Code Snippets is something you definitely want to check out.
Tip 3:
If you are a bunch of developers looking out for a free tool to record documentation online, use ‘Wikis’.
MediaWiki is a great piece of server-based software (wikipedia uses it), designed to be used between a large team of programmers, working on the same documentation. MediaWiki stores display data in a MySQL database. You can add notes, codes, faq’s, images etc. with revisions. Here’s a sandbox to try it out.
If you are a small developer team and want to store your documentation as text files (to be reused outside the wiki), you can use DokuWiki.
If you want a wiki solution for your own personal use, you can use TiddlyWiki which is a client-side reusable personal web notebook and a collaboration tool. It is like a one page personal blog designed like a wiki and can also be used as a personal productivity tool.
Tip 4:
You can use a free software like Evernote to records your random thoughts, ideas, things to do etc. You can even access it using your phone. It also gives an option to save webpage clippings and screenshots and you can write code snippets and search them later.
Tip 5:
Apart from the tips shared above, you can use an awesome professional tool like Microsoft OneNote to store, sync, organize, style, encrypt, backup and share your notes (to yourself, over a network or internet). Check a demo video.
I hope these tips will help you organize your notes, if you already haven’t been doing so. It’s never too late to start! If you have been using a tool that has worked wonders for you, feel free to share it using the comments section.
Tweet
About The Author
12 comments:
I use knowledgeroot with XAMPP as code-vault-wiki-database.
A better alternative to Snipplr is Code Barrel. It is also free, but much easier to set up and share with friends. It also integrates with popular IDE's. www.codebarrel.com
Really it comes down to good project management and writing a plan so you can look back at any time and RTFM you wrote.
I use several tools to keep track of my progress, which is really important because there are tax claims I can file for specific areas of my work, but I need to prove a lot of things to do that.
First, I use this awesome tool for time-tracking from toggl.com, it's a very light-weight UI cloud service that is surprisingly powerful and provides metrics and reporting-- as long as you get into the habit of typing 8 words a day into the text boxes you'll be set.
Second, I use something very similar to a discussion forum vs Reddit system, where I can start a project journal, keep my notes in it, and vote up/down the importance of the project for sorting. I can also close it. It's about 100 lines of code over 2 php files, and a two-table MySql database. I'm the only one using it, but I can go back whenever I want. The whole project took maybe an hour of my time.
Third, I keep a hand on things with a Gantt chart (looking after others deadlines and meeting your own ... this sort of thing really helps you). There's lots of gantt software out there, but I use a free one called "GanttProject" which is really easy to use, but has a few glitches I that can bother you (java software :P).
I had used a mediawiki in the past, but it didn't scale well for the size of my team (<5), it was too much hassle. I don't want to screw around with text formatting. The historical revisions was nice, but they aren't implemented logically for development purposes. It might be nice to use them later for full-scale projects when I need to fully spec out version 1.0, but while I'm developing it didn't make sense. I suppose this comes down to how you manage your project, is it agile? Waterfall? How big is your team? Who's going to read it? What's the goal of your documentation (replace yourself, distribute knowledge, historical data, tax reasons, proof of work, etc...)?
I really believe that your documentation standards depend on the scale of your project, size of your team, and scope for what your need to cover in your documentation. However, no documentation isn't acceptable for anything other than a quick script. Even then, you should probably add a line or two of comments.
I used to use TiddlyWiki, and it's great, but these days I'm a big fan of Evernote. Having my notes searchable across platforms (even my iphone/ipad) is awesome. I highly recommend it.
Yeah, I use the Code Barrel. Tried the Snipplr but eh, I like the interface of code barrel better. I agree with you, the whole cross platform thing is a need for sure. Evernote is cool, I use it for other things but for my code I liek the fact that code barrel was designed for exactly that purpose. I hate using tools as catch-alls. Like the drop-box. You know the saying, use the right tool for the job will save ya time!
I use Google Notebook. Unfortunately they have stopped support (only existing user can further use it).Google Documents is a less superiour alternative but also good for that.
Thanks for this nice article. Help to me with alternatives to Code Snippets.
The link about Snipplr is wrong. It should be http://snipplr.com
Thanks all for your comments
@BrianG: Thanks for sharing your experiences. I hadn't heard about toggl.com earlier, I will give it a shot. Although for deadline tracking, I use MS Project + TFS and it has worked fine for me.
MediaWiki is an overkill for a team < 5. DokuWiki is a good alternative for small teams.
@jetm - Sorry about the link. It has been corrected. Thanks
Thank you very much, very useful article...
All of those application and approaches are quite nice. But have one major drawback when compared with a simple pen and paper, you have to type.
My notes mostly consist of scribes on a peace of paper in my notebook. As soon as I can do that just as fast on the computer I will gladly jump and maybe even pay for it.
But for now I will keep with my analog pen and paper design.
I'd suggest checking out tomboy as an alternative to most of the tools posted here. It's a cross between evernote (notes are standalone docs) and a wiki (respects wikiword syntax), is cross platform and when combined with a tool like dropbox for syncing, can be used on multiple machines without hassle. The one drawback is lack of iphone app or similar, but I think there are some side projects aimed at exactly this. It's not truly cloud enabled, but with dropbox it's close.
Post a Comment