Re^7: An Introduction to Literate Programming with perlWEB

[BrowserUk]

When you're getting used to an unfamiliar code base, any hints at all are worthwhile.

If you put every routine into it's own module with it's own API to document, then there would be little difference between your position and mine.

On any project that runs to more than half a dozen files, there is absolutely a need for project documentation, separate from, and with a different target audience to User/API documentation. Targeted at maintainers, this should include such things as file layouts; internal structure layouts; the structure of the project directories and files; build, test and validation procedures etc.

But when you're first sitting down to explore and familiarise yourself with a project of this size, the last thing you want to have to do is stab around in the dark peeking inside source files at random trying to piece together an overview by picking out those bits of the embedded prose that relate to that overview, from those bits of that embedded prose that relate only to the local line, block, subroutine or file.

Not only does that make it difficult to form a coherent overview of the project initially. That difficulty persists throughout the life of the project for all concerned. Everyone--from programmers, to architects to managers to technical writers--waste an inordinate amount of time trying to remember not just what they read, but where they read it. It is all but impossible to index the information at any given level it for any target subset of users.

This type of project overview or architectural site map, absolutely does not belong spread across myriad source files mixed up with "this loop counter is unusual because it starts at -1" type local annotations.

You mean the experience of guys like Donald Knuth?

Hm. He has seriously long and deep experience yes, but of a very different kind to your average Joe Programmer, systems analyst or project architect.

It all comes back to my short answer in my original reply above.

His uses and needs of a documentation system are far and away different to those of your working stiff programmer or project leaders. He's targeting an entirely different type of audience; his goals are: absolute technical correctness, and understandability by first-year undergrads regardless of background; his timescales are measured in years, if not decades, rather than the days or weeks as for most commercial projects.

This puts me in mind of a heated discussion I had a dozen years ago with the head of HR for an extremely large organisation. Try as hard as I might, I could not convince her that two years of relevant experience was far superior to ten or more years of the irrelevant.