Recent days I added a big feature to my personal C++ project (a library).
There are totally 4700 lines of new code and 3000 lines of unit test code for the new feature.
I was very busy (on my casual time) and had some very tough time on debugging.
But, any way, I was quite HAPPY on what I was doing. And I had a lot of patience when writing and debugging code.

But now I must write documentation before I can release the new feature. It's not required by any boss because it's my personal project.
I have to write it, write some tutorial or guideline so others may know how to use the new feature before they download the package.
This is not my first time writting documentation.
Also this is not my first time, again, I nearly lost all my patience and feel quite stress on that.
This is not because that I'm writing in English which is not my native language. I will definitely get same feeling if I write in my native lanuage.
The reason is, I'm writing someting for old stuff (for the code I've written). What I'm doing is much much less creative or interesting than coding.

Seems I had rant enough, so now I want your experience or advice.

I believe some of you had same experience with me. I also believe a lot of programmers love coding but dislike documenting.
So, do you have any successful experience that you change your mind to accepting documenting happily, as happy as coding?
I tried and failed. I tried to have a break and play some TV games. But after I back to the computer and realized I have to work on documenting again, I feel not happy any more. :-(

So if you can share any trick to make me have more patience on writing documentation, I will appreciate a lot.

NOTE: What I said is just my personal experience. Don't get mislead to think documenting is painful. No, documenting should be not painful. Don't misunderstand that. :-)

As a personal philosophy, code without documentation is like a fish without water, i.e., its useless for anyone but the writer at the time of writing. Since most code is used by more than one person at some point, if it doesn't have documentation, its not very useful.

There are MANY ways to go about documenting your code. By absolute minimum, you should have signature declarations on what the arguments are and what you should expect to get and what its general purpose is (i.e., something akin to JavaDoc, NDoc, etc.). That gives people the bare minimum to figure out blindly how to use it... so, if you're not doing even that, then i hope you have a perfect memory, because in 6-mo to a year or two, you may not even know what you did. Great part about these is that a lot of it can be automated through most IDEs.

Comment everything. My best comments are ones that actually personify the software, and explain in Layman's terms what is going on. People relate to people easier than to machines or math, they're also 10x easier to write, but that is after you've moved into a personification mindset.

Examples/Scenarios are great as well, especially if you ever plan on sharing your code. They don't have to be spectacular, just choose one of your best test cases, and offer it as an example of what it does (i.e. re-use what you've already done).

UseCases can be helpful, but i find flowcharts of more use, (unless you're at a complex point in a system). In fact, sometimes all you need is a good descriptive flowchart rather than paragraphs of text and example. Google Docs has some workable free tools in this area. Not great, but its better than nothing.

With that said, the degree of documentation required is highly dependent on the context of the userbase. If you're just "putting it out there", then you don't need to go overboard, a decent declaration doc and some examples will suffice. If you're working on a project, you'll likely need a design doc with high-level concept and low-level conceptual descriptions of operations/use, perhaps some UML as required etc. If you're wanting to create a highly-used tool by the programming community at-large, you'll need all the above, with in-depth specs detailing everything.

Its a lengthy process, but if you want to share software, you have to provide Rosetta stones, otherwise people likely wont use it.

[edit: removed some text i felt was too argumentative]

I take the opposite approach and try to aim for zero comments. Unless you're using brainfuck or writing some clever algorithm, what you are doing with the code is often best expressed in the code itself. This means writing legible code with sensible function and variable names. In code I write that other people are going to consume, I would consider it a failure to have to write a comment to explain what I am doing.

Some more on the subject: http://apdevblog.com/comments-in-code/

I get what they are talking about in that blog, but it reads more like a guide of what -not- to do, rather than saying why comments are bad. If you're commenting so much you have more comments than code: you're doing it wrong!

The main issue is that commenting code is very contextually subjective, so there is no "one size fits all" answer. My moniker is: "if it isn't blatantly obvious what I'm doing or more importantly -why- i'm doing it", provide a minor comment.

I get what they are talking about in that blog, but it reads more like a guide of what -not- to do, rather than saying why comments are bad.[/quote]
Indeed, those examples had nothing to do with actual commenting and, in some cases, were the result of too little, not too much.

I also believe a lot of programmers love coding but dislike documenting.[/quote]
For the most part, I believe it's a workflow issue. It's a lot like writing test cases, in my experience: if you don't do it from the start, it becomes exponentially more difficult to justify - mentally - the investment as the amount of "up front" work increases as you continue development without doing so. In a lot of cases, as the Gnome has said, leveraging an IDE will make this much less obnoxious. For in-code documentation, there's a lot of boundary cases you can use to legitimately weasel out of writing anything (@see tags, etc.).

For out-of-code documentation, I find that format matters a great deal. LaTeX, mark[up/down], APT, XDoc, etc. Using an application format you don't find comfortable is a huge turnoff.

With that said, the degree of documentation required is highly dependent on the context of the userbase. If you're just "putting it out there", then you don't need to go overboard[/quote]
Bolded for emphasis. In the past, because I actually do love to write, I have written lengthy disserations on projects that, frankly, did not need them. Doing so is an excellent way to burn yourself out and waste a lot of time in the process.

Personally i use doxygen and add the necessary comments to my code for it to work and along with graphwiz pretty much all of my documentation is generated automatically based on comments in the code. (Writing those comments is a bit of a chore though as they usually are quite redundant but getting up to date, easily browsed (This really is the key point) documentation for the entire project makes it worth it).

But now I must write documentation before I can release the new feature[/quote]
Why?

I have to write it, write some tutorial or guideline so others may know how to use the new feature before they download the package.[/quote]

"I have to".

Do you?

Who are your users? Why are they using the library? How?

Do they need documentation? Can they just read the commit logs? Look at unit tests?

If they do need it, what kind? Why? Can you provide 5 line sample of how to call new feature?


Ideal library for me is one that just works without reading anything.
Second best is one which integrates automatically.
Third is one that has as few lines of documentation as possible, preferably single digit.

I'm a user. I want library to solve problems. I need a car to drive, not to tweak under the hood. Libraries which require a lot of tweaking tend to be less valuable or they attempt to cover too much ground.

But if something comes with 1000 word introduction and 100 page reference manual - it better be something really important and preferably expensive.


There's also a saying: If you can't explain it simply, you don't understand it well enough (or something similar). Which is part of reason why TDD took hold in many places. Can you document new functionality in 5 lines of code? If not, why? Is there really need for that much more?


Take a step back and look at the simplest possible thing. Not the library, the code, documentation - which problem does your library solve?

Look at unit tests?

This is often a better approach to comments and documentation. If the tests pass, they are probably the best way to see how the library is used. I can't tell you how many times I have gotten frustrated trying to work with a library which had out of date documentation. There is no indication that it is out of date, things just appear to not work! The documentation doesn't "break" when it doesn't match what the library does anymore, but automated tests will! The same is true with comments in code. On numerous occasions the comments were not maintained and no longer reflect the functionality that is present. I maintain that no comments is better than incorrect and misleading comments, and when code is written "properly" you should only need comments very rarely.

Thanks all for your valuable input.

About code comment. No, I'm not commenting the code. Indeed I rarely comment the code. I try to keep my code self-understandable. The code itself is already some kind of comment.

Also I'm not writing user manual, it's overkill for me and nobody will read it unless it's as high quality as MSDN. :-)

But I do believe some tutorial is quite helpful. When I looking at a library web page, if it has a tutorial to let me know how it works, I may have interesting in continue investigating on it. Otherwise, why should I spend my time on reading the library code like a mystery black box while I have no idea how it works? There is less motivation to do it.

In my opinion, tutorial + sample code is the best documentation for users' start. How do you think? Anything else I should consider?

I maintain that no comments is better than incorrect and misleading comments, and when code is written "properly" you should only need comments very rarely.

Can't agree more.
Recently I used a library. I try to use a function described in its online document, but there is no such a function.
Then I read the offline doc in the package, seems that function had gone...
I would like there is no doc for that library...