Documentation review
Brought to you by:
cbegin
Menu
▾
▴
Looking at the 2.0 docs, I think they could use some TLC.
Two things I have noticed about the docs is that (1) they are not organized clearly, and (2) they are big enough now to need a ToC. It is hard to believe how much new material is in them - the doc was less than 30 pages last summer, now it is 52! That is a mixed blessing - there is more good stuff, but it is harder to find.
I also started thinking more about Java-specific versus other platforms, too. Much of the current doc is very Java-centric, and addresses issues that would not be a concern to a .NET coder, for instance.
So, to get us past the blank sheet of paper, I will give a layout that I think could work for this. We can start with this, or if I am full of crap, we can just throw it away. :-P
(Sorry, the layout sucks, but sf.net is not exactly QuarkXPress!)
===
- Table of Contents
- Introduction
-- Purpose / Concept
-- Vision
-- Installation
--- Platform specific instructions
- Configuration
-- SQL Map Config file
--- Overview
--- Elements
--- Loading and persisting
-- SQL Map files
--- Overview
--- Elements
--- Types and Aliases
--- Parameter Maps
--- Result Maps
--- Dynamic Statements
--- Caching
--- Advanced Topics
- Programming
-- Platform specific APIs
- Patterns
-- Common patterns (platform independent)
- Index
Thoughts? Opinions? Random utterances?
Larry
Hi Larry,
I love the idea of starting the docs from scratch. They are certainly dated. Have you seen the TO-DO list regarding docs?
As for platform independence, I'm not a fan of abstracting our documentation. I'd personally like to keep it as specific as possible. If there's one thing that should be absolutely concrete in a software system, it's the documentation.
That's not to say that we couldn't have a repository of doclets that we could maintain that applies to both. But at this time, I think it's just as well that the docs be separate. At some future point we can mine good ideas and "doclets" from each of the platform docs.
Clinton
That is probably the simplest route - it could make more work later, but for now it would get us moving quickly.
Ahh...now that's agile thinking. Don't worry about later. For software, "later" may come and go before it's even done. Let's get the most value for our time now.
LarryDocs rock!
Clinton