I'm taking some time to work on the Tapestry documentation ... starting with the FAQ. It's great fun, though this could get to be quite large. I'm just spewing out content right now, over time we'll clean it up, reorganize it, and add further hyperlinks and annotations.
In fact, as I'm working on the FAQ, I'm thinking this might be the best way to document open source projects in general. User's guides and reference documents are rarely read, everyone just Google's their question, so put those questions in their most findable format. Also, it's hard to write a consistent user guide start to finish ... but more reasonable to document one tidbit at a time.
Also, I'm reminded of The Little Schemer, a book that teaches the entire Scheme language (a Lisp variant) via a series of questions of ever broadening scope.
Feel free to suggest additional FAQ topics on the Tapestry Users mailing list.
4 comments:
FAQ is definitely not the best way of documenting an open source project. Personally I always start reading User's Guide which "guides you" with the initial steps and beyond.
Next, a cook book is something I always look for, as FAQ usually only suggests the solution, not solves it, many times assuming the reader understands every word in the Answer.
As a long time Tapestry observer/user I very much miss good and accurate components documentation. That includes several use cases for every component and how to use them with best practices.
What I really do not understand is why Tapestry does not include numerous components developed by the community and T5 core commiters? Why there is no some kind of plan which components should be included in next versions? There are only two new components and two mixins in T5.2 which was developed for 14 months. I know I could contribute, but I just do not understand why for example there is no Tree component included just for example. And there are tons of others wished for (http://www.questionpro.com/akira/ShowResults?id=1151880&mode=data).
Isn't there a mojor rewrite going on for Tapestry official page?
And I wish forward for the translated book!
End of big T5 fan rant.
A FAQ can be one part of your documentation, but it shouldn't be the backbone of your docs.
Think about learning a new language (a human language, not a computer one.) Generally speaking, handing you only a dictionary on day 1 isn't going to make you a fluent speaker. You may need a series of examples, from simple to more complex, and an understanding of the concepts (and culture) before you can start constructing meaningful sentences and talk about new things.
At a minimum, Tapestry could use:
- A quick start tutorial or two, just to get new adopters up and running.
- A guide to the major concepts and usage patterns within Tapestry (with examples)
- Enough information on the major components that a relatively new user can put them to use. In some case, this may even require a component-speciifc guide if the component is complex enough.
- The Javadocs (which you do a lovely job on)
...and then the FAQ to fill in gaps between the reference docs and the formal guides. A FAQ can document a common pitfall or question that doesn't fit naturally into the other documentation.
...Richard
Tapestry is a very configurable beast with many ways to override the default behaviour. It would be great to have a list of all the services that can be overridden or contributed to and the type of configuration (mapped, ordered, unordered) required. Perhaps a build time task could grep the codebase for this information?
@Lance: Tapestry has excellent JavaDoc, supplemented by specialized annotations just to express details such as the configuration type. What's missing is a higher-order description of how the key services work together. I have documentation for that in my Workshop.
I'm actually excited about the Confluence wiki for documentation, partly because it integrates with Griffy to create detailed charts and diagrams relatively seamlessly.
Tapestry has about 120 services built in, and one of my clients' applications starts up with about 600 services (many of which are actually Quartz jobs).
Post a Comment