One of the weaknesses of many open source projects is documentation,
and I don't think that sipXecs can claim to be an exception (yet).
We've got a lot of material in the current wiki [1], but it has a
number of problems:
* Much of it is very dated.
There are warnings about problems that were fixed several releases
ago, and descriptions of how to do complicated things that we now
have simple solutions for. Screen shots rarely match the current
look of pages.
* Documentation for users is not clearly separated from internal
developer documentation (which generally make both harder to use
and produce).
* It's not well integrated with our other project tools.
Administration and access control uses a separate account system,
and mediawiki doesn't have features to integrate with the issue
tracker and other tools we've moved to.
* It's not in the sipfoundry.org domain (for historical reasons that
no longer apply).
Some time ago, we got licenses from Atlassian (free - thank you
Atlassian) for many of their excellent tools: the Jira/Greenhopper
issue tracker and planning tool, the Fisheys/Crucible code browsing
and reviewing system, the Crowd central user administration and
single-signon system, and the Confluence wiki.
For various reasons, we've delayed starting to use the Confluence
wiki; it has for quite some time been set up at [2], but we've not
moved any content to it or used it except experimentally.
I propose that as one of our New Years Resolutions for 2010 we resolve
to improve our project documentation dramatically. I think that using
Confluence offers us some real advantages toward that goal:
* Generally I think Confluence is a nicer wiki tool than mediawiki:
* It has nice built-in commenting features (configuring permission to
comment is separate from permission to edit pages, which is much
more open than we have now).
* The editing is easier (and more robust - I think that the
automatic saves of draft changes in progress may justify the
move all by itself). There are better wysiwyg editing modes (for
those who like wysiwyg).
* It is well integrated with the other tools. Not only does it use
the same account management and single-signon that the other tools
use, but it supports incorporating content from them. For example,
you can include a link to the results of a Jira filter or a
particular issue in a wiki page so that current status is available
as a part of the user documentation.
* It supports 'Personal spaces': each user with write access has
their own space in which to create personal content (and decide who
and when it can be seen or edited by others). These are very handy
for developing pages for proposals or notes on what you're doing;
when the time comes those pages can be moved into the appropriate
project space.
I've proposed a general framework for how to organize content in the
wiki built around the use of Confluence 'spaces' [3]. The framework
of the proposed organization is already in place - read the details on
this page in my 'personal space':
http://wiki.sipfoundry.org/display/~xmlscott/Proposed+sipXecs+wiki+organization
There is a tool to automatically convert mediawiki content to
Confluence. I've done some test runs on representative content, and
while there is a little tweaking required, the basic conversion is
quite usable. If we agree to migrate, we can automatically import the
content from the current wiki into a new read-only space and then move
the pages into the appropriate places in the new hierarchy while doing
the tweaking.
I've posted this to both of our lists to get everyone involved in the
discussion... because the wiki is mostly (especially now) about
supporting users, I've directed replies to the users list only.
[1] http://sipx-wiki.calivia.com/index.php/Main_Page
[2] http://wiki.sipfoundry.org/display/sipXecs
[3] http://confluence.atlassian.com/display/DOC/Working+with+Spaces+Overview
_______________________________________________
sipx-dev mailing list [email protected]
List Archive: http://list.sipfoundry.org/archive/sipx-dev
Unsubscribe: http://list.sipfoundry.org/mailman/listinfo/sipx-dev
sipXecs IP PBX -- http://www.sipfoundry.org/
