We believe that this approach can be a substantial improvement over the way that technical documentation is usually handled in a real-world software project. The usual practice is to write the documentation separately from the program and keep it as a separate artifact. This has several disadvantages.

Too often, the technical documentation is an afterthought, not written until after the program is finished. The energy and excitement that the programmer feel while writing the program are gone, and so documentation becomes a half-hearted effort, sometimes done only grudgingly. And by then the programmer may have forgotten important points such as why certain design decisions were made the way they were.

Even worse, the technical documentation may be neglected as the software changes. Almost all software is changed over and over during its lifetime: to correct defects, to improve it, and to adapt it to changing circumstances. Too often, the documentation is not changed to match, so that the documentation becomes increasingly out-of-date and inaccurate, and ultimately worthless.

We believe that literate programming encourages the programmer to record thoughts and important points while they are fresh; and later, when making any changes to the code, to make any necessary changes to the technical documentation (which is right there with the code) at the same time. And we hope that it will help programmers to take some of the same energy and pride of creation that they apply to their programs and extend it to the exposition that explains the programs. Certainly Knuth approaches programming this way, and so do we.