Clear and Concise

On the Fly

2009-03-06T23:07:00.000-08:00

The original premise when I started this blog was to discuss how Web 2.0 technologies and open source software are changing the way that products and services are documented. Document collaboration among a community of authors (and not just a single team of writers) is becoming the norm with open source software projects such as Glassfish and Ruby on Rails using blogs and wikis for discussions and draft reviews. The influence of document collaboration will become more pervasive as (once) proprietary products such as databases and operating systems incorporate open source components (such as MySQL Enterprise and Red Hat Enterprise Linux).

An even more fundamental change than the increased use of document collaboration tools is the way that software products and services are being developed. As customer requirements demand more flexibility and quicker response in planning and implementation, companies are adopting agile development processes that focus more on working software than formal detailed specifications. The foundation of agile development are principles where software is planned, implemented, and tested "on the fly" so that project teams work closely with customers as requirements change, rather than treat change as an impediment to the development process. For more information, a presentation on agile development (in particular the Scrum methodology) is available here from the Scrum Alliance.

The impact on conventional product documentation (from user guides to online help) is potentially huge when a project team adopts an agile development process. No longer can writers use formal specifications as a negotiating point with project teams to determine the number, scope, or schedule of document deliverables. Likewise, writers can no longer rely on formal specifications to provide the gist of the information that will be fleshed out during the draft development and review cycle. Instead, the de-emphasis on formal specifications in agile development means that writers must be able to install and configure the software from working prototypes to the final version in order to create the needed task, reference, and conceptual documentation.

Scott W. Ambler wrote an excellent article detailing the documentation issues for agile development. Some of the insights that he shares are:

The fundamental issue is communication among team members, not formal documentation.
Write documentation if that's the best way to achieve relevant goals, but there are often better ways to achieve these goals than static documentation (such as an online help system that focuses only on a single product release or version).
Document information that is stable (not speculative).
Seek (then act) on feedback on a regular basis throughout the document draft and review process.

Because of the iterative nature of agile development, Ambler notes that a best practice should be to wait until the information has stabilized before you capture it in documentation. It is risky to capture speculative information, such as requirements or design details, early in the lifecycle because those details are likely to change.

To give you some idea of the current (and likely) demands for someone wishing to create documentation on an agile project, you can look at a wiki article intended to describe the administration console for an open source project. As with the rigor of agile development, the administration console underwent significant UI changes between the November 2008 community milestone build to the current Beta build in January 2009 -- requiring a total of 38 draft revisions to the original wiki article posted in November (and likewise supporting the decision that a conventional online help system for the console was too risky at that stage in the development). To track all those changes, myself and another writer became part SME (knowing what the software is supposed to do), part system administrator (install & configure software), part QA engineer (figure out what the software actually does and doesn't do) before we can even devote time to the task of actually writing.

This effectively means that writers are no longer insulated from the software development and QA testing processes with a unique process just for product documentation. Writers will increasingly be asked (if not required) to participate as peers on the project team during agile software development, or else their jobs will (most likely) become redundant.

It's Not What You Say, But How You Say It (Part 2)

2009-02-09T10:03:00.000-08:00

I said in a previous post that, while community wikis are a valuable opportunity to solicit feedback, they cannot replace the requirement for dedicated writers to create task, reference, and conceptual documentation for a given product or service. Yet, I did not acknowledge at the time that community members have an "enlightened" self interest to keep the wikis accurate and up to date.

Two articles that were contributed to the Liferay community wiki (as part of an open source partnership) brought this to mind. The first wiki article had updates incorporated by a community member after the article was first posted. The other wiki article illustrated the opportunity for community members to discuss possible revisions/updates after the article was first posted.

Such input/feedback could not be incorporated at the time that these articles were written because, to be honest, the authors of the articles couldn't anticipate everything that the users would need to know (or want to know). Indeed, there is wisdom in saying that the community is greater than the sum of its members.

I have summarized the effort needed to contribute articles to the Liferay community wiki (with an eye towards creating documentation for a future commercial release) on my wiki.

It's Not What You Say, But How You Say It

2009-02-05T12:25:00.000-08:00

I haven't gotten any user comments on the articles that have posted to the community wiki. But, just for argument's sake, I do get comments from users just after I start together the review draft of the product documentation (which are based on the wiki articles). Do I incorporate the user comments as part of the product documentation as I would review feedback from the project team? Or should I just collect the user comments and have the product team review them for completeness and accuracy (as is done with bug reports)?

In other words, should a documentation wiki for an open source project be considered as complete and accurate when the product documentation is available separately? Or, more to the point, can a documentation wiki replace the need for separate product documentation?

My past experience working on open source documentation projects is that, while community wikis are a valuable opportunity to solicit feedback, they cannot replace the need for dedicated writers to create the required task, reference, and conceptual documentation. In other words, someone has to bake the cake before others can get a taste.

Perhaps the ideal role that community wikis can play will be to provide a forum to discuss how to fill the gaps in the product documentation over the life of the product, perhaps starting with planning and deployment issues (at the beginning of the product lifecycle) to upgrade and migration issues (when the next product release is available).

Originally posted to blogs.sun.com by J. Aseo on 10/31/08. You can find a summary of the effort needed to support the Project SocialSite community wiki (with an eye towards creating documentation for a future commercial release) on my wiki.

If a Tree Falls in the Forest...

2009-02-05T12:11:00.000-08:00

I wrote my first blog about my issues with blogs and wikis (specifically blogging to arouse user interest in an early draft of an article). So...after a full month of revisions incorporating feedback from the project team after first posting my article to the wiki, I think the content is now "complete" (or at least it incorporates everything that everyone on the team can think of). Then comes the deafening silence of no responses from the community...kind of like that saying "If a tree falls in the forest, and no one is around to hear it, does it make a sound?"

At first, I'm more than a little discouraged, because wikis are supposed to be this wave of the future that will bring about the age of collaborative documentation and forever break down the walls between professional technical communicators and the user community

But perhaps I'm just being skeptical--it took 20 years before desktop publishing moved from the realm of graphic designers to everyday users. Things take time, and good ideas like wikis will eventually move from the realm of computer geeks to everyday users.

So, I guess I'll just continue to keep posting articles, being well aware that community feedback may be slow in coming (if at all at first). But if you plant a seed, and the seed grows up to be a tree, then someday that tree just might make a "boom" and someone will be around to hear the sound.

Originally posted to blogs.sun.com by J. Aseo on 10/31/08. You can find a summary of the effort needed to support the Project SocialSite community wiki (with an eye towards creating documentation for a future commercial release) on my wiki.

Not Ready for Prime Time

2009-02-05T11:03:00.000-08:00

So, I post to the community wiki an early draft of an article that is barely more than topic sentences with no real detail. Then I get the edict to post a blog to the community to encourage feedback. I thought my blog was pretty innocuous, until the one of the project engineers and the engineering manager realize that I'm blogging about features that really isn't ready, and that the community would have little interest in providing input and feedback. So, after I had (unsuccessfully) spent two weeks of asking the engineers for feedback on the article before I first posted, I managed to get enough additional detail to post a revised draft that may have enough content to actually pique the interest of the community and actually get feedback.

So, the process of collaborating with the community on open source documentation is somewhat hindered by the fact that evangelism of the community often occurs at the same time (to drum up support). It seems to me like a situation of putting the horse before the cart. You may just need stable software builds (with real features) before you can write articles that you can circulate to the community for comment.

I guess the devil is in the details.

Originally posted to blogs.sun.com by J. Aseo on 10/31/08. You can find a summary of the effort needed to support the Project SocialSite community wiki (with an eye towards creating documentation for a future commercial release) on my wiki.