[Computerbank] Documentation (long)

[Steve Paynter]

Hi Jo-Anne,

--- Jo-Anne <jo_bianchi at dingoblue.net.au> wrote:
> Hi everyone
> Some of you will know me, but I will be a new name to those of you
> outside Victoria. I am both a user of Computerbank services and a
> volunteer at Computerbank. I am currently studying Technical Writing as
> part of my Diploma of Professional Writing and Editing. My final
> assignment for the year involves writing a case study on the use of
> documentation in a company or organization, so I am doing mine on
> Computerbank.

The cb-doc documentation project was started by Trish Fraser early July 2001,
I think.  I joined about a week later.  From the beginning, the project was
hosted from sourceforge.net, so the archives are a complete record of e-mails
from that date up to start of Sept 2001, after which it went offline.  They'd
make an excellent basis for a case study!

> I would greatly appreciate input from everyone associated with
> Computerbank about the documentation in the organization. I will post
> some basic questions and hope that as many of you as possible give me
> some feedback.
> This is also a good opportunity for the subject of documentation to be
> discussed and maybe create the incentive for more people to contribute
> to the creation and maintainance of documentation within Computerbank.
>
> Here are a few subjects I would like to know more about.
> How important do you think documentation is to the organization.

Absolutely critical.  If it's not written down, then it's in someone's head
(bad) or has been forgotten (worse(?)).
Also, we're hoping user documentation will *substantially* reduce our
telephone support load.

> Should there be more of any type of documents?

There should be less of all types of documents. Except the good ones.
More of those, please.  :)

> Should there be more cheat sheets? If so what topics should be
> documented?
> Have you ever read any of Computerbank Policy documents?

Has any non-Committee person ever read *any* policy documents?  Not me.

> What documentation from Computerbank have you used?
> Did you find it effective ? Why or why not?

None.  Mostly, I don't know where the final copies are kept!  Scattered
about cbv, I think.  In the office, and the training room.  And the work-
shop?  Apparently, most of the draft versions live with Kylie.  A few nights
ago they were in crooked piles on the cbv training room floor, for a
documentation meeting.
Kylie writes most of our documentation.  Did I mention that?  Yay, Kylie.

I've started a repository for electronic versions. For various reasons we're
retiring sourceforge for the moment.
We have several hundred docs in total.  The repository is way incomplete.

> How is the documentation in Computerbank created?
> Who creates it?

Documentation people as at Aug 2001, according to sourceforge:

David Hatton        Project Manager
Grant Diffey        Doc Writer
Kylie Davies        Doc Writer
Penni Diffey        Editorial/Content Writer
Peter Eckersley     Editorial/Content Writer
Jo-Anne Bianchi     Editorial/Content Writer
Jonathan Burns      Project Manager
Steve Paynter       Editorial/Content Writer
Simon J Porter      Editorial/Content Writer
Patricia Fraser     Editorial/Content Writer
Jacqueline McNally  Doc Writer

Much of this list is out of date (the third line is still current!)

> Who can make changes to documentation?

Future plans: Anyone can make changes. Source will be online and freely
accessible. Versioning will track who changed what. Full document history
always available. This was the original reason for using sourceforge.
This is apparently what cvs is all about. I should know more about this.  :)

> Who decides what documents will contain?
> Who must approve of any documentation created?

I had a crack at resolving such issues in late July; see attachment.  The plan
was made during a period of tension amongst some members of the group.  It was
not (publicly) supported.  These issues were never again addressed, to my
knowledge.

> How is the documentation distributed?
> Who has access to particular types of documentation?

Future plans: Electronically, on clients' machines and over the web.
Paper too.

> Is Computerbank documentation widely used?

Excellent question.  Any takers?
Future plans: it will be.  Support calls will go: "Hello... Have you
consulted the online documentation? No? Please go away now."

> Is Computerbank documentation effective?
> What changes would you like to see in the way documentation is used at
> Computerbank?
>
> You get the general picture... answer one, answer them all or tell me
> something else; but, please answer me ASAP. (Yes I have put this off too
> long and the due date is drawing near. )
>
> I look forward to some interesting discussion of this topic.
> If you have something you would like to discuss with me in private
> please contact me at jo_bianchi at dingoblue.net.au
> Thanks
>
> Jo-Anne Bianchi


I'll detail current status and "future plans" in another post, if
anyone's interested.

What are other states doing about documentation?

Steve.



=====
==========================================
Steve Paynter
sbpaynter at yahoo.com.au
PO Box 4127, University of Melbourne, 3052

__________________________________________________
Do You Yahoo!?
Make a great connection at Yahoo! Personals.
http://personals.yahoo.com
-------------- next part --------------
A non-text attachment was scrubbed...
Name: msgs
Type: application/octet-stream
Size: 3238 bytes
Desc: msgs
Url : http://lists.linux.org.au/pipermail/computerbank/attachments/20011015/674d6e3a/attachment.obj