Joel Spolsky Launches Trello - Organize Anything Together

Re:Joel Spolsky Launches Trello - Organize Anything Together by vog on Wednesday September 14, 2011 @04:50AM (#2995416)

I believe this is called literate programming (LP), which focuses on real documentation (in the broader sense, including specs, etc) rather than mere API docs. There are quite a lot of LP tools, many of them being independent from the language.

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.

[ Parent | on HN ]

Re:Joel Spolsky Launches Trello - Organize Anything Together by olavk on Wednesday September 14, 2011 @06:40AM (#2995650)

That is interesting, and perhaps part of what I am looking for.

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

[ Parent | on HN ]

Re:Joel Spolsky Launches Trello - Organize Anything Together by vog on Wednesday September 14, 2011 @07:10AM (#2995721)

Why not? For instance, feature proposals are just the previous phase of high-level requirements. And high-level requirements are just the previous phase of (or introduction into) the spec.

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.

[ Parent | on HN ]

Re:Joel Spolsky Launches Trello - Organize Anything Together by drothlis on Wednesday September 14, 2011 @05:08AM (#2995451)

Have you written up your approach to / experiences with literate programming anywhere?

[ Parent | on HN ]

Re:Joel Spolsky Launches Trello - Organize Anything Together by vog on Wednesday September 14, 2011 @08:13AM (#2995899)

I'm not an expert on that topic, others have written it up better than I could:

- 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

[ Parent | on HN ]