The Future of Documentation
I recently posted my thoughts on where a much better form of documentation than Rdoc and Yard. Let your docs live with your codebase. I’d love to hear more thoughts on this idea! Specifically, what libraries that do NOT lend themselves to this style of documenting? Are there any patterns we can discover?
Comments
Your idea has merit, as often some of the most useful information lies dormant amidst various examples and tests. However, I still think that, when done correctly, traditional-style documentation is most useful. In particular, TomDoc looks to be a good solution which finds a compromise between comment readability and machine parsing - I can never quite accept HTML in comments.
I’m also a little scared of overly publicising portions of code which are essentially for testing. As much as we would like to say they don’t, dirty hacks do pop up every now and then, even in Cucumber. I prefer an application to include an ugly test than not test the feature at all, and your proposal may cause the opposite effect. That said, it may cause some people to take more care in testing, and that can only be a good thing!
I also vote for TomDoc of Github fame … Clear syntax, on the fly, no hassle and fully flexible
Thanks for the comments! I wasn’t aware of TomDoc, it looks like what the Rails team is using. One downside to Cucumber documentation is that you lose the ability to just explain something in words. Perhaps a combined Cucumber/TomDoc approach would work even better where you use Cucumber to show examples of using your library and TomDoc when you need to explain in more detail.
I like your idea mostly because true “literate programming” and documentation standards are fun to discuss but almost no-one uses them consistently or over a long period of time. Cucumber features, though, people are already writing them..
I concur with your experiences of coming to understand an API through the tests. It is a pleasure and one that I can rely on to do the explaining for me, saving both the developer and me, the consumer, the hassle of something that may or may not work.
Similar to Relishapp I started an extension of YARD which parses your cucumber feature files and creates searchable and browsable documentation (example).
I agree with this somewhat. But we definitely shouldn’t limit ourselves to just using one or the other. Sure, looking at features/specs is a good way to figure things out as an end user. But a comment here and there in the source code is also helpful for developers looking to fix a bug, which is important in our open sourced world :)
Another nice thing about documenting code is easily showing arguments etc (esp hash ones). A person should not have to dig into the source code for that.
I also think a well written README is important, since it usually covers 90% of the use cases.
I love the simplicity of coffeescript’s author literate programming utility.
http://jashkenas.github.com/docco/
It is not an API document generator. We need something with the features of TomDoc and docco.
Anyone ever tried using just cucumber?
Is there any reason natural language is not applicable to say unit tests?
Would they be more informative than well-written specs?
I wrote <a href=”http://rubyworks.github.com/qed>QED</a> for this very purpose.
I wrote QED for this very purpose.
Post a comment