Wish List for Open Source Docs

This is my feature wish list for a documentation system that would make it possible to easily interact with the open source community--and eventually, to enable augmented collaboration of all kinds. Of course, I see it being implemented with DITA and JRuby, but only because they meet the critical requirements listed here:

  • A Wiki-accessible, WebDAV-enabled repository that handles XML objects, allowing them to be edited as Wiki text, in an online WYSIWYG editor, or with a remote editor.

  • Online pages with comment capability and multi-level access the allows viewing, commenting, comment administration, or editing, depending on authorization.

  • Fine-grained notification settings to users can be notified of all changes to a page, or only major changes, with independent settings for pages the user has authored, pages the user has edited, and pages the user has bookmarked, with overrides on individual pages.

  • "Spanning" controls for access and notifications, so you can set them at different nodes in the information hierarchy and have them apply to the subtree rooted at that node.

  • Support for document structures that allow for multi-dimensional conditionals at all levels of the information hierarchy, transclusions, and independent specialization.

  • Link checking and doc-linting of the above to maintain quality.

  • An integrated build, translation, and document-on-demand system that produces PDF, HTML, Help, printed books, online tutorials, and classroom materials.

Resources

Ruby

DITA

Collaboration

Comments:

Hallo Eric
Yes, wouldn't it be nice! I'm using Confluence wiki. The wiki has a lot of the functionality you're looking for, but is certainly not the whole answer. And it's not Ruby ;)
# Wiki - yes; WebDAV-enabled - yes; XML objects - yes, but not DITA; online WYSIWYG editor - yes; RPC calls - yes.
# Online pages with comment capability and multi-level access that allows viewing, commenting, comment administration, or editing, depending on authorization - yes.
# Fine-grained notification settings - not as fine-grained as you'd like, but fairly comprehensive none the less.
# "Spanning" controls for access and notifications - yes, to a certain extent: space-level (where a space is a kind of wiki within a wiki) and page-level.
# Multi-dimensional conditionals at all levels of the information hierarchy - no; transclusions - yes; indpendent specialization - not sure what this means.
# Link checking - yes, when internal within the wiki; and doc-linting - not sure what this means.
# Export to PDF - yes; HTML - yes; Help - not CHM or Winhelp; Word format - yes, at page-level only.

Have you taken a look at Confluence? And what do you think of DITA Storm?
Cheers --- Sarah (ffeathers)

Posted by Sarah Maddox on February 08, 2008 at 12:38 PM PST #

Thanks for the comments, Sarah.

Confluence is one heck of a nice Wiki. Gotta admit that. They're really responsive, too. That much I know about it. Thanks for telling me a bunch of stuff I /didn't/ know, or wasn't sure of.

The most interesting future-use-case I see is for a Wiki front end with DITA at the back end. There are a world of features that go into making such a system work, and I like (J)Ruby for that, but it's not an absolute requirement, given that JRuby can integrate with a Java-based application like Confluence.

DitaStorm is another interesting technology to keep our collective eye on. It will be worth watching. I'm sure that what I'm about to say will become outdated, in time (and I'm equally sure I'll miss it, when it does), but my take on DitaStorm at the moment is that it implements a very limited subset of DITA. It seems to work great as long as it is only editing topics it created. But at the moment it fails rapidly when editing topics created by any other editor.

Bob Doyle found the perfect application for it when he created his DITA test-bed at the Boston Computer Society. Anyone can log in, create some DITA topics, and see the deliverables produced by the Open Toolkit. It's a /very/ friendly way to get started, and since all topics are created by DitaStorm, the system seems to work quite well. (But the open questions are whether that functionality is sufficient in a production enviroment, and whether restricting users to that single editor is acceptable.)

Within those constraints, however, DitaStorm seems to be a solid solution that works. And I'm sure it will grow over time. This criticism will become meaningless, at the point.

Posted by Eric Armstrong on February 11, 2008 at 08:43 AM PST #

Post a Comment:
  • HTML Syntax: NOT allowed
Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today