[OPEN-ILS-DOCUMENTATION] documented developmnt

[Grace Dunbar]

On 2/9/11 2:40 PM, Dan Scott wrote:
> Sounds great! I'm encouraged by our collective recognition that
> delivering functionality without documentation in past releases was
> probably not a great idea on our part (collectively) and am very
> grateful to DIG for having made up so much ground in the past year.
Agreed!
Okay, I think maybe our conversation has gotten a wee bit out of scope.  
And I'd like to hear what DIG has to say so let me just recap what I 
think is germane from our back and forth for those that don't want to 
slog through the emails. (Please add anything you think I left out.) 
(edited to include some of Lori's comments, too - thanks for chiming in 
Lori!)

Small-scale projects (minor customizations, small widgets) are easier to 
build documentation for from initial specs than large scale projects 
with a high number of dependencies.  We know this to be true but don't 
have a solution yet on how we can make that process better.

It would be a Good Thing to have all new functionality to be accompanied 
by at least a basic amount of documentation.

Basic documentation might include things like:

-list of required permissions and descriptions
-basic description of intended use cases
-basic outline of intended order of steps
-brief description of UI layout and features
-known issues

Perhaps a decision needs to be made on how general documentation should 
be approached: (or perhaps this decision was already made?)
     - workflow/how-to with supporting feature information
     - general feature overview and explanation with supporting workflows
     - something else that we didn't think of....

It would also be a Good Thing if the development community did a better 
job keeping the "under development" area of the wiki up to date and 
current with basic outlines of projects describing intended 
functionality, features, etc.

It remains to be seen if the community or DIG believes that 
documentation should be:
- written and revised as any development project proceeds
- written at the functional end of development when features are more 
solidified and systematic testing of the feature begins
- some other thing that we didn't think of...

Perhaps some group should be responsible for making sure that all new 
development features have adequate basic documentation.

DIG should possibly be tasked with determining if basic documentation 
provided meets the standard.

Lori also asked if the following could be provided or mapped out with 
more certainty:
a) feature set of the current release
b) what features will be added to the next release(s)
c) what is actively being worked on (by all developers), and
d) what are some features or enhancements that users have an interest in 
seeing developed (and how critical are they and who shares that interest 
and who has money to pay for their development).  The web team has been 
calling this one the "wish list."

(I think all but "b" are doable and "b" is something that can be updated 
as features *are* added.)

We can all do better at sharing information and helping out our fellow 
Evergreeners in the community.
We are all wonderful committed people with a healthy appetite for debate.
:-D

Thanks!
Grace

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20110209/1dcbd4cd/attachment.htm