[dmckeon]

Comment first: project the document instead of documenting the project. In other words, write the comments first, then write the code, then review and tidy up both the code and comments.

By writing the text first, you clarify the why before you write the how. You also capture the high-level view before you get down to the gnarly details, after which the high-level view can become a vague ghost of a memory.

Once that high-level view is left behind, many people become so immersed in the coding details that "introductory" material written after coding often begins with the esoteric details of the implementation of the central algorithm, and fails to mention what the tool/packages/code/app is for in the first place.

To put it another way, documenting is to code as foreplay is to sex. Both code and sex can be effective without comments or foreplay, for some values of effective, but they are more likely to be more pleasant and repeatable over time if people put in a little time and effort before rushing ahead to what they see as the most interesting parts.