This page is a bit confusing.
1) The order and organization of the documents does not seem to follow
any logical pattern. Perhaps there should be some sections to help
direct the reader a bit.
There are documents that a new system administrator would read.
Some are for a person wanting to customize the system by adding an
application.
Some are for the PMC.
Some appear to be background material
Grouping the documents into sections will make it easier to find what a
new person needs to know based on their current task.
When writing documentation for systems that we have built, my
instructions to the people writing documentation is to clearly
understand the "hat" that the person is wearing when they read the document.
Are they wearing their System Administrator hat or their Business
Analyst hat or their Developer's hat, etc.
Even if the audience is often a single person in each organization, they
may play several roles and need the information for each role packaged
in a way that they can find it.
This also makes it a bit easier to write the documents if you consider
the background and interests of the person based on the "hat" you expect
them to be wearing when they read it.
2) Some of the documents are very old and I would think that some are
either obsolete ( to do lists of things that are done already) or
describe ideas/tasks that were never accepted.
Perhaps there could be an "Archived Documents" page that holds the links
to these pages if there is a concern about getting rid of them altogether.
If someone from the PMC would work with me on this, I would be pleased
to try to fix up this page.
Ron
1) The order and organization of the documents does not seem to follow
any logical pattern. Perhaps there should be some sections to help
direct the reader a bit.
There are documents that a new system administrator would read.
Some are for a person wanting to customize the system by adding an
application.
Some are for the PMC.
Some appear to be background material
Grouping the documents into sections will make it easier to find what a
new person needs to know based on their current task.
When writing documentation for systems that we have built, my
instructions to the people writing documentation is to clearly
understand the "hat" that the person is wearing when they read the document.
Are they wearing their System Administrator hat or their Business
Analyst hat or their Developer's hat, etc.
Even if the audience is often a single person in each organization, they
may play several roles and need the information for each role packaged
in a way that they can find it.
This also makes it a bit easier to write the documents if you consider
the background and interests of the person based on the "hat" you expect
them to be wearing when they read it.
2) Some of the documents are very old and I would think that some are
either obsolete ( to do lists of things that are done already) or
describe ideas/tasks that were never accepted.
Perhaps there could be an "Archived Documents" page that holds the links
to these pages if there is a concern about getting rid of them altogether.
If someone from the PMC would work with me on this, I would be pleased
to try to fix up this page.
Ron