Scott, I'm looking forward to the new Wiki and I'm sure the rest of the community will as well. This will be a good opportunity to reorganize the content so things are much easier to locate.
On the organization of the Wiki, I guess I'll need to see how things roll-up from version to version in the new Wiki software. I'm sure we can come up with something better than it was before... better, stronger, faster. Thanks, Mike -----Original Message----- From: [email protected] [mailto:[email protected]] On Behalf Of Scott Lawrence Sent: Monday, December 21, 2009 3:09 PM To: sipXecs developers; sipXecs users Subject: [sipX-dev] Improving the sipXecs project documentation wiki - aproposal 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+organ ization 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/ _______________________________________________ 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/
