Posted: Fri Oct 28, 2005 12:38 am Post subject: [Asterisk-doc] (interesting announcement) New Document Manag
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!
Posted: Fri Oct 28, 2005 12:53 am Post subject: [Asterisk-doc] (interesting announcement) New Document Manag
On 10/28/05, Sean Wheller <sean@inwords.co.za> wrote:
Quote:
On Friday 28 October 2005 10:38, Leif Madsen wrote:
> * Check-in / Check-out capabilities directly from a web interface --
> no more end-user CVS required
Interesting. Let's start by knowing where the current web interface can be
found.
Heh... guess in all my eagerness (and it being 4:54 AM here) I forgot
a link. Be sure you're a Registered member and logged in to see
anything useful.
Posted: Fri Oct 28, 2005 12:54 am Post subject: [Asterisk-doc] (interesting announcement) New Document Manag
On 10/28/05, Sean Wheller <sean@inwords.co.za> wrote:
Quote:
On Friday 28 October 2005 10:38, Leif Madsen wrote:
> * Check-in / Check-out capabilities directly from a web interface --
> no more end-user CVS required
Interesting. Let's start by knowing where the current web interface can be
found.
... or the more common way:
Go to http://www.asteriskdocs.org
Login
Under the Main Menu section of the left bar, click Document Management System
Posted: Sat Oct 29, 2005 1:11 am Post subject: [Asterisk-doc] (interesting announcement) New Document Manag
Leif Madsen wrote:
Quote:
* 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.
ASCI?? A-Z only? I believe DocBook can handle more, since it's XML and
XML by nature is unicode. Guess this was a mistake, but what character
set are we supposed to use? As we move Asterisk to a more international
way of handling characters, we need support for ??? and even more
interesting characters :-)
Posted: Sat Oct 29, 2005 3:27 pm Post subject: [Asterisk-doc] (interesting announcement) New Document Manag
On 10/29/05, Olle E. Johansson <oej@edvina.net> wrote:
Quote:
Leif Madsen wrote:
> * 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.
ASCI?? A-Z only? I believe DocBook can handle more, since it's XML and
XML by nature is unicode. Guess this was a mistake, but what character
set are we supposed to use? As we move Asterisk to a more international
way of handling characters, we need support for ??? and even more
interesting characters :-)
Heh, yes, you are totally correct in that I was mistaken with the term
"ASCII". What I meant was plaintext, and I tend to (incorrectly)
substitute ASCII for plain text.
As for us North Americans being more sensitive to the world community,
we need to be more aware of the use of special characters and be sure
our goals take this into account. As we see Asterisk start to support
a more international character set, those of us in the documentation
arena also need to keep up. Luckily I have people like you, Olle, to
keep me in line :)
You cannot post new topics in this forum You cannot reply to topics in this forum You cannot edit your posts in this forum You cannot delete your posts in this forum You cannot vote in polls in this forum