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.
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.
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.
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:
