Hi all,
I was thinking about modules documentation as I've just submitted some
work and I wish to discuss with you a proposal regarding a
re-organization.
I think actual module documentation structure doesn't help us all to
find the right place to put our docs and consideration and thus
doesn't ease our efforts, so here is my idea:
- in the index page we present a generic description of WHAT the
module accomplish and a descriptive list of the main features
- in the quick-start page we describe how to install the module with
the minimal effort, using pre configured example, scripts and other
already prepared stuff, with links to more detailed informations
- in the user-manual page we give more informations about module
configuration and extensibility giving hints on how things are managed
internally
- in the faq we try to answer to the generic questions we receive on
the list so we will be able to answer to a question with just a link
- in the howto (another faq like page) we try to answer to technical
questions we receive on the list
I'll try to give an example using smartweb-auth (the better documented
module) as an example.
- index
the module provides authentication, authorization and accounting
features to the (blah blah blah)
* features
- extensible authentication and authorization mechanism
- customizable auto-registration process
- scopeable authorizations, meaning you can authorize not only
on functions but even on business elements
- blah blah blah
- quick-start
* step 0
download the smartweb-auth jar (link to latest release), the sql
schema creation script for your database and blah blah blah
* step 1
run the database script
* step 2
run the initialization script to insert default values
* step 3
blah blah blah
- user-manual
this manual is divied into n sections...(list of sections)
* module configuration
the module configuration file is structured in this way blah blah blah
* extending authentication mechanism
to extend the authentication mechanism you need blah blah blah
here (link to the howto) is an example
* extending the authorization mechanism
(as before)
* blah blah blah
- faq
(as we have right now, but giving away the more technical questions
in the style of how to
* is the user password transmitted in clear on the wire?
* may I use POJO to identify a scope?
- how-to
(usage and extension examples with technical questions)
* how to extend the authentication mechanism to use an asymmetric
key instead of a password?
* how to specify blah blah blah
Let me know your impressions... IMHO this will simplify our
documentation efforts.... We should be able to quickly find where to
place that piece of information which actually don't fit anywhere...
In addition we can consider the wiki as a place where we can manage
the how-tos... but until now I have to admit we are not using the
wiki.... how come?
--
Roberto Lo Giacco
|
