MM,
To avoid a long learning curve, I'd suggest to handle the documentation as a project itself, and the output is a 'system' of documents.
I personally found it very useful to use the use case pattern, especially the Actors/Stakeholder viewpoint. Here's what I did in a situation like yours (not exactly, but imho producing a process documentation comes quite near:-):
1. Identify Actors, in your case: your readers
2. Interview them regarding their expecations for the documents
2.1 Listen mostly, don't try to offer suggestions during the interview
2.2 Some questions that prooven useful for me:
* What decisions will be made based on the document input?
* Why is the information documented important for you?
* How often will you revisit the document?
* Do you have examples for such a document you want to have?
3. Based on the interviews, your first work product would be the documentation overview or a document index
3.1 start with 1 document per Reader Role (if two readers have the same responsibilities, they share one role)
3.2 Name the documents & their purpose only, don't put content in them (yet:-)
4. Get a sign-off by upper management to start working on the documents
5. Start searching for templates & examples
5.1. Ask your system providers (SUN in your case at least) what they use to document - they usually have a broad experience & oversight on how their systems are documented by other customers
5.2 Adopt the templates for your needs (rule of thumb: a template where you only remove sections is more useful than a template where you have to add sections)
6. Sign of the templates (!not! the content)
7. Fill the templates with content
8. deliver finalized documents and get sign-offs where needed
I personally found it good to do some review juggling before handing over a final version of a document:
* let the main stakholder officially sign off the layout & structure of the document independently and before you finalize the content
* let other readers (with similiar experience, independent of their role) review early versions of the document.
* The earlier you review a document, the less change efforts/time you will need.
Hope this helps & havagoodone!
Volker
Main Topics
Browse All Topics
by: TallBoyPosted on 2009-01-14 at 09:10:10ID: 23374917
We use Twiki (http://twiki.org/) to document our systems and applications, usually by function ("email", "infrastructure", "user-login" etc).