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 _______________________________________________ Asterisk-Doc mailing list [email protected] http://lists.digium.com/mailman/listinfo/asterisk-doc
