Subscribe to RSS
Posts Tagged ‘DITA wiki’
DITA round up
Just doing a little data mining of the posts I’ve written about DITA in the last few years. I think that there’s a gap for DITA users who are writers or content creators and not coders. I’d like to say that DITA bloggers can bridge that gap. Join me on the DITA blog by writing your own experiences with DITA.
These posts are ordered from newest to oldest, and I wrote them to share my experiences with DITA and to chronicle some of the Central Texas DITA User Group meetings I attended.
A watched folder for publishing from DITA source files
June 15, 2007: I’ve figured out a way to automate DITA builds where you just drop a zip file of your DITA source files into a “watched folder” and PDF and CHM files are automatically built.
Usability and inline links in user assistance systems
May 19, 2007: Examining DITA’s linking and usability.
Getting Started with DITA
April 12, 2007: A brief overview for a couple of fellow Austin writers who have asked me recently how and where to get started with DITA.
Checking out the new DITA Users website
April 10, 2007: Using a coupon code (it’s BETA) I joined the new DITA Users website for free today.
A new DITA Open ToolKit release and brand new DITA newbie blog
October 04, 2006 : A couple of blog-worthy items in the DITA world
Turning information into DITA topics
September 14, 2006: What would you do to make this particular type of content into topics?
How to substitute your custom CSS when using DITA Open Toolkit transforms
September 07, 2006 : When you want to use the DITA Open Toolkit transforms but you want to use your own CSS, here’s how to substitute your CSS for HTML Help (CHM)
DITA Open ToolKit now has a User Guide
August 22, 2006: Just released last week, the DITA Open ToolKit now has its own User Guide
Using the DITA catalog for your specializations, creating a Public ID
August 16, 2006 : Thought our discovery might help you as you specialize DITA
Evaluating XML editors for DITA
August 01, 2006: Notes from the July 2006 Central Texas DITA User Group meeting
A web-form-based DITA editor
July 14, 2006: Could this be the perfect storm for a DITA wiki?
Troubleshooting tip for the DITA Open Toolkit install
June 23, 2006 : Finally figured out the fix for my DITA Open Toolkit “resource/messages.xml” not found error
Where to put your files and other setup for DITA
June 09, 2006: Working with the environment setup for DITA
Defining OPML and relating to DITA maps
May 31, 2006: I found a nice definition for OPML from whatis.com as their word of the day, and I’m starting to wonder about similarities between OPML and DITA maps
Learning more about DITA
May 18, 2006: Learning about how to get started with DITA and a trivia item for fun
Notes from the central Texas DITA user group meeting
April 21, 2006: Two speakers shared their takeaways from DITA 2006 and CMS 2006
Our DITA experience at BMC Software
March 02, 2006: Link to a case study published about BMC’s DITA experience
DITA from the trenches
February 20, 2006: Information Architect from IBM, Kristin Thomas, presented to the Central Texas DITA User’s Group meeting last week, and here are my notes.
Moving from Books to Topic-oriented Writing
January 27, 2006 : A report from JoAnn Hackos’ talk at the Central Texas DITA Users Group meeting January 2006
DITA and wiki combo
December 05, 2005: Darwin Information Typing Architecture, meet Wiki.
Darwin Information Typing Architecture - DITA (dih tuh)
November 04, 2005: Roundup of the DITA reading I’ve been diving back in to lately.
What if users wrote the manuals?
Inner gang? Mini empires? Am I talking about the online encyclopedia, Wikipedia? Why yes, yes I am. I’m reading “Who Writes Wikipedia” which is a study on how Wikipedia is edited and maintained. Is it really “a small group of colleagues working together toward a common goal?” A small group wrote that much content in about four years?
I’m interested in this subject because Wikipedia is a wonderful reference site full of content that usually is accurate and rings of authority even though it is maintained with an all-volunteer content creation and editing team. Seeing it and liking the results, I wonder how a wiki could be used in a similar fashion to build technical documentation sites that are user-built and maintained while offering the best, most thorough, most accurate technical information about a certain product or technical subject. Could we really get as valuable a reference for product doc by having a “small group of colleagues working together towards a common goal” — a goal of an excellent set of product documentation online?
Outsiders provide content, insiders clean it up
Come to find out, according to the article, over half of the edits are done by less than 1% of the users, about 500 people are considered to be the inner circle of editors, building consistency in wording and categories while fixing typos and editing content where needed to build more quality into each entry. The most active group of about 1400 people have done nearly three-quarters of all the edits. These statistics and claims are made by Jimbo Wales, the face of Wikipedia. Now, the article’s author, Aaron Swartz, tracks a few more nuances of this claim by studying random wikipedia entries, such as the one for Alan Alda. And here is his conclusion based on his study:
When you put it all together, the story become clear: an outsider makes one edit to add a chunk of information, then insiders make several edits tweaking and reformatting it. In addition, insiders rack up thousands of edits doing things like changing the name of a category across the entire site — the kind of thing only insiders deeply care about. As a result, insiders account for the vast majority of the edits. But it’s the outsiders who provide nearly all of the content.
Wiki for tech doc
Now, I’d like to try to translate this to what might work well for a wiki geared toward product documentation. You’d need a core set of very knowledgeable content providers, like a team of experienced users of the product. Those users would contribute a core body of knowledge to the wiki, and hopefully choose to first document the items that are either most popular tasks or the most-referenced information or the toughest concepts to grasp. Most likely that would be the subject matter they’d be most familiar with anyway.
But is there vandalism?
It also appears that my wiki graffiti concerns are likely unfounded… the article says, “A tiny handful — probably around 5 out of nearly 400 — were “vandalism”: confused or malicious people adding things that simply didn’t fit, followed by someone undoing their change. That’s such a small percentage, just over a tenth of a percent, that it seems for the most part there are few writers with malicious intent in their edits.
Real wiki writers tell their experiences
Reading through the comments, I also appreciated the “user experiences” from people who are actively editing Wikipedia content. One commenter notes that he “went crazy” adding content in areas where he had knowledge but found that once his knowledge limitations were surpassed or the well was dry, he went into a maintenance mode. With a “burst of new knowledge” he’d add more content to those areas but found those to be few and far between. I think that with product documentation a similar ebb and flow would occur — knowledge or experience with a relatively new feature would cause activity on certain articles but then maintenance would occur again.
How do you get enough contributors?
Probably the major limiter for a product documentation wiki that’s maintained by users is that the user base would have to be significantly large in order to draw enough content providers. If 500 people maintain Wikipedia, you’d probably need 50,000 users to get 500 committed people to provide content (or would you actually need half a million?).
How do you ensure consistency?
Wikipedia has a basic information model to follow that most people are familiar with, also — the encyclopedia and it’s article-like writing style and the content you expect to see in an encyclopedia is well known and the style is easily copied by any writer. Product reference would need some excellent modeling to follow, which is why I lurve the idea of a DITA wiki — structured content models that 500 people could follow consistently, writing concept topics, tasks, or reference topics on a regular basis.
I’m warming up to the wiki
We can learn a lot from Wikipedia’s success and I plan to continue to track their progress as it evolves and more policy is put in place. Perhaps the wiki has potential as a great product doc format.
What do you think as a writer? Would you be willing to write and maintain content for product doc in a wiki? What do you think as a product user? Would you want to read and would you trust the content provided by thousands of fellow product users? Maybe I should experiment by combining the two groups — user and writer — and start a FrameMaker wiki. Surely the FrameMaker user base just isn’t large enough to generate the content it would need to succeed. What do you think?
A web-form based DITA editor
Written with just HTML, Javascript, DOM, and CSS, as far as I can tell, DITA Storm is a product that enables web-form-based DITA topic authoring and display. Go check it out, their web site has a lot more content now and you can even request a copy with which to play.
As my help infrastructure buddy said, “This is so cool I think I’m going to freak out like this kid. Nintendo Sixty-FOOOOOOOOOOUR” Yep, it’s Friday, so yep, it’s a video link. Just go watch it, and get a good laugh.
I’m imagining that you could do several things with a web-based DITA editor (and topic styler). One thing would be a DITA-based wiki, where you author directly using DITA topics rather than some cryptic ASCII codes for headings and bulleted lists and so forth. End users don’t have to know DITA to enter content, either. Although I do think you’d want to also be able to copy and paste content from existing DITA topics, and I’m not sure how you’d do that (maybe there’s a “view XML code” feature in the works?). Although you can just link right to the XML topic from within the HTML page, which would be nifty for DITA topics you already had waiting in the wings.
According to the web site, “The prototype version 0.3 of DITA Storm supports following DITA elements: topic, title, shortdesc, body, section, title, note, lq, q, fn, related-links, link, linktext, desc, p, b, i, u, tt, sup, sub, task, taskbody, context, result, steps, step, cmd, stepresult.” So it is a subset of DITA so far (others are subsetting DITA but it’s not really DITA once you subset it and you can’t import DITA-compliant content later into your subsetted set. Whew.).
Another idea for using DITA Storm for end-user doc might be to build your context-sensitive help system right in with your web interface product. I suppose this idea would work only if you can lock down the content at a certain point. But the stylizing with CSS is very promising and really lets you do anything you want with the content. The stylized examples are really nice looking, such as a stylized task topic and a stylized basic topic.
And, my pet idea would also be to use DITA Storm to write blog entries. Entering blog posts in a structured language like XML would work right in with the microformatting concept. Build the next blogger.com site using DITA Storm.
This type of product in my estimation has the potential to be the next Writely, stealing from the desktop publishing user base with the beauty and simplicity of a web editor that just gets the job done. Yes, it’s another way of writing, but a nifty little tool that could help your content do some interesting cartwheels.
