[Asterisk-doc] (interesting announcement) New Document Management System (DMS) at ADP

[Leif Madsen]

Today I've been playing and experimenting with a new Document
Management System (DMS) for use by the Asterisk Documentation Project.
This new system will allow us to bring a document from draft stage all
the way through various steps and approval processes in order to
create professional, community created documentation. I'm very excited
about this new process of document creation!

I have written a couple of README files which still need to be
proof-read and updated as we take our first document through the
system. Here are some of the advantages to using the new DMS system:

* Check-in / Check-out capabilities directly from a web interface --
no more end-user CVS required

* Work with documentation in ASCII format. This allows people to use
any editor, however simple, that they wish. This will also make it
easier to convert to DocBook format after the document has been
written.

* No longer need to deal with DocBook if you don't wish to. The
document creation and DocBook conversion are now separate steps --
makes document creation simpler!

* Work through the document creation process in "steps" using "Life
cycles". A life cycle can be applied to a document, which is then
promoted or demoted (rarely), bringing the document through various
stages. Different permissions on the file are automatically set based
on which step in the process the document is involved in.

* No more lost documents and confusion on the mailing lists (although
this is still used for discussion during document creation)

* Notification system to alert Core team members know when a document
has been changed or its status promoted.

* A more logical document creation process -- with more documentation
explaining the process in a pair of README files. These files will be
updated as we run a few documents through the new process

* Not forced to write a whole book -- focus now on shorter, more
focused documents called "articles" -- new article template file in
the Document Templates directory of the DMS system.

The new system should allow for a more focused and logical approach to
document creation by breaking it up into smaller chunks. The web
interface is fairly intuitive and should lower the barrier of entry to
creating documentation. With the new focus being around shorter
documents rather than full books, this should allow more documentation
to be provided by the Asterisk Documentation Project team. Once we
have enough articles on a subject, or group of subjects, we can
combine them together to create books if it makes sense.

The first article through the system will be Gene Naden's "Connection
to a PRI". I've already uploaded the document to the DMS system, and
will be taking it through the steps of the DMS over the coming days. I
will also be updating the README.documentation_process and
README.docbook_process documents throughout this period.

If people would like to get involved with this initial process and
learn it so that we can improve the DocBook template we're using, and
to refine how documents are created by us, feel free! I'm going to
lead it up, but the more the merrier.

Also, if you have idea's of which documents are "must haves", then let
me know as well (if you're the first to suggest something, please
create a new thread -- please verify if you're the first, and if not,
reply to the newly created thread. I will eventually put the ideas up
on a website poll and we'll start working through creating the
documents in order of demand.

Suggestions for refining this process are welcome!

--
Leif Madsen - http://www.leifmadsen.com
http://www.asteriskdocs.org -- Co-Founder
http://www.oreilly.com/catalog/asterisk -- Co-Author