4 ms·

I would really like a tool that would allow a spec and development notes to evolve just as a program evolves. It should start out with being as simple and low-o

by olavk 15y ago

I would really like a tool that would allow a spec and development notes to evolve just as a program evolves. It should start out with being as simple and low-overhead to use as a few post-it notes, but as the projects gets bigger it should be possible to impose structure, like categorize notes into functional spec or requirement, user stories etc, prioritize etc.

vog 15y ago
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.
- drothlis 15y ago
  Have you written up your approach to / experiences with literate programming anywhere?
  - vog 15y ago
    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://en.wikipedia.org/wiki/Literate_programming - http://www.literateprogramming.com/ 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 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 http://www.profv.de/uni/kuenstliche_intelligenz/aufgabe3.pdf
- olavk 15y ago
  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.
  - vog 15y ago
    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.

by olavk 15y ago

vog 15y ago

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.

drothlis 15y ago
Have you written up your approach to / experiences with literate programming anywhere?
- vog 15y ago
  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://en.wikipedia.org/wiki/Literate_programming - http://www.literateprogramming.com/ 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 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 http://www.profv.de/uni/kuenstliche_intelligenz/aufgabe3.pdf
olavk 15y ago
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.
- vog 15y ago
  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.