Basically -- if you're building something big and complicated and you should know exactly how it's going to work, a big written spec really helps.

If you're building something brand new, a startup, or a crazy idea that you need to test quickly and iterate, you should use lots of little specs. It's ok if the specs aren't so fancy... a detailed map of what goes on the screen and what everything does is probably fine. It's ideal if you write lots of small specs for each small feature ("user story") right before you implement them and roll them out.

I just don't like the idea of typing code when you haven't thought through what it's supposed to do (in a disciplined way). Doing specs in small quick chunks, then writing code, is probably the best approach for lean/agile startup teams that don't yet have customer/product fit.

It's easy to see someone jumping in and writing and re-writing code when they haven't thought it through as wasteful. People have a harder time seeing that writing and re-writing specs can be similarly wasteful.

I think Joel's comment of "thinking in a disciplined way before typing code" hits the nail on the head. Different people can think in disciplined ways before typing code. Some people do that by writing specs, other people do that by writing tests, others do it at the whiteboard. There's no one right way to do it.

I also think the same thing happens when we write software with loose mental maps. Our brains fill in the gaps with "yadda yadda yadda," to make it feel complete, but really there's nothing there at all.

Practical suggestion that has worked for me is to use graph paper. Having the grid to align and separate things makes a huge difference. My non-graph-paper sketches look like something from a lunatic's diary in comparison.

I would be eager to try a whiteboard with a consistent faint grid to it.

However, LP is not about tools. I've written LP programs that don't need any extra tool[1]. Rather, LP is about putting the documentation (spec, requirements, etc) at the highest level, and make the code a sublevel of that. This is very different from the traditional approaches where code is the highest level, or where documentation and code are separate.

[1] This worked because the build script was part of the literate program, too. Many "problems" with LP solve themselves if you just apply LP consequently.

But I'm not sure that things like feature proposals, high-level requirements and architecture overviews fits into a literate programming model.

I'd think of it as a big documentation where some parts are complete and mature (down to the level of code), while other parts are still in draft (feature proposals).

Or change management: Of course everything should be under version control. And I guess that bug descriptions should still be part of a ticket system or at least the commit messages. But I never understood why feature proposals are discussed more in a discussion-based manner (ticket system) rather than a document-based manner (wiki, or documentation).

Unfortunately, I was never part of a development team which was seriously into LP, so my suggestions are only based on my understanding of LP, and small proof-of-concepts on my own.

I'd love to read about bigger real-world projects which apply LP, or which at least apply some other documentation-driven approach.

- http://en.wikipedia.org/wiki/Literate_programming

- http://www.literateprogramming.com/

Nevertheless, I have done some experiments. Some time ago I submitted a small demonstration about "Self-Contained Literate Programming" to HN. It seems to have vanished, so I just resubmitted it. It would be great to get some feedback/discussion about that:

- http://news.ycombinator.com/item?id=2995845

Together with some other students, I also created some homework for university in LP style (sorry, in German language only):

- http://www.profv.de/uni/kuenstliche_intelligenz/aufgabe3.pdf