This is one reason why I really like Doxygen, in the areas where it's supported. It's not only very easy to generate easy-to-read documentation for the code while writing it (specialized comments, with operators to call out special meanings and so forth), but it's also very easy to create high-level documentation from exactly the parts that contribute to it. (Section, page, etc. commands.) Not to mention, then generate a nice, easy HTML stack of it all with pages, search-ability, etc.
I've never really agreed with the whole "code should be just be obvious when read." The problem with any large set of instructions is that both the instruction, order, combinations, and other artifacts reflect the experience, background, and environment of the author. Two developers of largely equivalent experience and talent rarely come up with the same set of instructions for the same task.
Consider if I told you how an engine functioned as a means of telling you how to change a head gasket.
I've never really agreed with the whole "code should be just be obvious when read." The problem with any large set of instructions is that both the instruction, order, combinations, and other artifacts reflect the experience, background, and environment of the author. Two developers of largely equivalent experience and talent rarely come up with the same set of instructions for the same task.
Consider if I told you how an engine functioned as a means of telling you how to change a head gasket.