So I'm working on the docs a bit, and am thinking that it'd be good to
have a 'Documentor's Guide', just like we have a 'Developer's Guide'.
There are a lot of interesting patterns in Confluence that I'm noticing
we use in our docs, and it'd be nice to articulate some of them. It
also would be nice to explain our general layout as well.
I'm also wondering how much we should attempt to break things down into
separate pages. One thought is that it would be nice to get a high
degree of 'doc reuse'. We could approach this with links, or could use
confluence {include} stuff, which can be a nice pattern. It'd also be
cool to do something like have a FAQ that is just made up of pieces
that are documented elsewhere, since most anything on a FAQ you would
probably also like to read as you're just working your way through the
documentation. I also liked David's convention on our OWS docs of
having 'definition' pages. We can obviously link straight there for
things like featureType and SLD, indeed mentions of those in the docs
should also be links (would be cool if we could have auto linking like
postnuke does, but I don't know if confluence supports it. Feature
Request?). Similarly in the GEOSDOC stuff we can have definitions for
things like Servlet Container - things that will be mentioned multiple
times that some users may not really know.
I think we should also draw up a page to introduce new users, like how
to sign up for a confluence account, point at the documentation guide
in confluence/codehaus, point at places where the docs need help, and
point to the developers guide.
Chris
----------------------------------------------------------
This mail sent through IMP: https://webmail.limegroup.com/