Searching for the Perfect Inline Code Documentation Tool

I have an intense love automatic documentation generation. Nothing makes me more tickled pink than seeing code and documentation living side by side in perfect harmony. I hate seeing documentation put on the company intranet only to diverge from the code it’s supposed to explain as the days go past. I hate hitting my head against a brick wall as I’m pouring through the source code trying to understand an API because at no point does it mention that it’s documented in a Word doc in another directory.

This is my rule of programming: documentation should live beside the code it documents, in the comments, especially if it’s API documentation.

Do You Make These Mistakes with Wikis? 9 Ways To Build a Wiki That Doesn’t Suck

There’s something about the hint of fall in the air that has always appealed to me. It’s my favorite time of the year, and as the seasons change I find the motivation to apply change to my own life. Last month I had the epiphany that I’ve been far too busy and I need to get a handle on the way I spend my time. The Internet is buzzing about using David Allen’s Getting to Done system to be more productive. There are a hundred and one different software tools you can use with the system; for the past week I’ve been using a personal wiki software called d-cubed/d3 gtd to do it.

Astute readers may guess from the title that there’s a rant coming up, and I want to prefix to say that I have nothing against d-cubed/d3 gtd. It’s good software. I respect Tom, the guy who built it, and appreciate what he’s done and how he’s available for help. I’m still using and enjoying d-cubed/d3 gtd. No, my beef is with the entire foundation behind d3: that dark Hawaiian voodoo called wiki.

• What’s a Wiki?
• Why Do Wikis Suck?
• 9 Ways to Make a Wiki That Doesn’t Suck

Automatic Documentation of Python Code using Doxygen

All programming is maintenance programming — code and documentation should always go hand in hand. Whenever documentation exists in a seperate file it always seems to drift away from the code.

This is a guide for automatically generating documentation off of Python source code using the open-source tool Doxygen.

Inline source code documentation (Language independent)

I am a firm believer that code documentation belongs as mark-up inside the code. It is natural that as code changes it drifts away from the documentation. When the documentation and the code reside in the same file at least there is a chance that they might remain in lock-step. Programmers are lazy (otherwise known as “overworked”), any having to make updates in multiple places is a recipe for disaster.

Creating HTML documentation of Verilog code

v2html is a perl script for generating beautified HTML representation of a Verilog design. The outputted HTML can be used to navigate signals throughout the source code (although there are many other commerical tools that can do the same thing now).
The parser can be used as a stand-alone perl module, and could be a useful [...]

What is semantic markup, and why does it matter?

This is an interesting essay talking about the difference between semantic and non-semantic markup. The gist is that marking up what the data means makes it more valuable, and that the non-semantic visual appearance can be broken apart from the semantic meaning (like CSS and HTML, although that it’s a clear boundary).
He puts together some [...]

Become an Excel ninja

Learning the most you can from Microsoft Excel.

Moving up the wisdom hierarchy // Creating Passionate Users

One of the writers from the “Heads First” series of books has an interesting post that the fundamental flaw with most technical documentation is that it focuses on the “What” instead of the higher levels of thinking.
The Data-Information-Knowledge-Wisdom hierarchy explained

Wisdom (systems thinking)
If and When

Understanding (grokking)
Why

Knowledge (useful patterns)
How

Information (organized data)
What

Data

Some key things to add to [...]

LaTeX: from beginner to TeXPert

Tutorial on getting started with LaTeX.
General Disarray » Blog Archive » LaTeX: from beginner to TeXPert

Ten things every Microsoft Word user should know

The general gist is that most people treat word processors like a typewriter instead of using the software features to automate a lot of the styles they would be attempting using manual formatting. Having recently come off of writing a 70 page technical document, some of these techniques are so dead-on. Although I feel that [...]

Python and Doxygen — Automatically Document Your Python Code

Python & Doxygen
You may have heard of Doxygen, a program that generates source code documentation by directly reading the source files and extracting the documentation from there. Unfortunately, doxygen can’t read Python code directly (it was originally written to extract documentation from C/C code). However, it is possible to apply a filter to [...]

Perl Doxygen Filter — Automatically Document Your Perl Code

About Perl Doxygen Filter
Of course, Perl developers are used to use POD rather than some other code documentation tools. However, most developers actually are not restricted to using one single language. Instead of using multiple code documentation systems one tends to use one tool for all - Doxygen is quite a powerful code documentation system [...]

Doxygen — Generate Documentation from Code Comments

Doxygen

Doxygen is a documentation system for C , C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors) and to some extent PHP, C#, and D.It can help you in three ways:
1. It can generate an on-line documentation browser (in HTML) and/or an off-line reference manual (in $mbox{LaTeX}$) from a set of documented source files. [...]