Matt Haughey is, amongst bloggers, pretty well known and respected. He recently wrote up his thoughts on weblog applications and, as they mirror some of my thinking, I thought I’d expand on this theme here.

The title of the post, Bottom line, all weblog apps suck in some way, was borne of frustration and outlines a few points which, reading between the lines, boil down to the same kind of thing.

Few web applications are at the point they could be considered a product.

Matt talks specifically about weblog applications, one of which I use to power this site (WordPress). I do a little web design in my spare time (there’s an oxymoron if ever I heard one) and have a similar working pattern as Matt; create template then drop in the code required by the weblog application, then tweak, tweak, tweak. I share his bemusement at the way Movable Type is configured, and I definitely agree with him when he says:

My ideal blog engine company would hire some seasoned blogger and technical writer to be a documentation czar, keeping docs up to date when new versions are launched, produce screencasts for introductory users, and provide complete documentation at a stable URL that applies to every version of the product. If an outside site does a better job of collecting and offering templates, a documentation leader should recognize that and link to them in highly visible places. There doesn’t seem to be anyone internal at these companies fighting for the users to make sure they can keep being informed about how to best use the product.

All of my knowledge of WordPress, Blogger and Movable Type (three of the biggest weblog applications) comes from tinkering about in the code, trial and error, and random Google searches. Sometimes those searches will take me to the website of the application, but more often than not they take me elsewhere to someone who has solved my problem already, or has a good solution that could be adapted to meet my requirements.

The information is a far more important to me than the weblog application, particularly as most of those meet my requirements and, as I’ve mentioned elsewhere on this website, the supporting information becomes the differentiator which will sway me one way or the other.

Let me repeat what I said previously:

Quite simply, products include documentation, support and training, and tell a cohesive story to a potential user. A story that says, yes this product will do X, Y and Z, and if it breaks we’ll do our best to help fix it, and we’ll support you as you learn to use it throughout the lifetime of your relationship with the product (and, therefore, the company).

The really good thing about this situation is that there is an opening here, a wide gaping hole into which a willing technical writer could leap. Most of the weblog applications are open source and would welcome you with open arms. The role Matt outlines is a huge one, but is perfectly within the reach of most technical writers. You know, if I had any spare time I might just try to get involved…

If you are working in an Agile environment, and don’t have “single source” in mind when you write then you are slowing yourself down.

Working in an Extreme Programming environment (an Agile methodology that our Development Group follows) brings a unique set of challenges. During the early stages of a release, we spend a couple of days thinking about what we will be building, writing out the requirements as customer-focussed stories and breaking down those stories into discrete, small, chunks of work each of which has an estimated time for completion.

We don’t have a project plan, and as we work in tight iterations with functionality being released on a regular basis, there is always the chance that the scope will change at some point, generally with little warning. The system is built to deal with this so it’s not as bad as it sounds but it does throw up some challenges for the technical writer.

However with a little thought and awareness it’s a very easy system to work within, but does mean we need to push into other areas a little more.

First up you need to get involved when the developers are writing up the stories. Sit in the customer meetings and any planning meetings. Be the user advocate. Ask questions now. Stories are written from the perspective of the customer (with that customer being the person who requested the functionality) and you can (should!) help to craft these properly, making sure each story remains customer and real-world focussed. Every story, regardless of the functionality that will eventually support it, is a high-level requirement and should be stated as such. The actual work might be to make an object persistent, but the story will only say “The customer wants to be able to view previous transactions for each account”.

You should also be present during the break down of the work. At this point, with each story being broken down into small chunks of work for the development team, you can gain a better understanding of the functionality, including any presumptions and dependencies that may be added. Each piece of work should be no longer than a few days, less is better, and you can start to build an idea of the scope of work during these discussions. As yet I’ve not found any direct corrolation between X days of development work to Y days of documentation work.

So, from the stories, you should have a good idea of the high-level functionality that is being produced, and you can create an outline of the documentation that is required. You should also, having sat in on the discussions, understand the requirements of the customer and the reasoning as to why a certain piece of functionality is, or isn’t, being developed.

The chunks of work can help to feed into each section in your outline, and working to the same principles as the development group, you can estimate each section. Even if the figures are never published, it’s a good idea to take a stab at guess-timating the work based on what you know, allowing scope for research and playing with the software. These guess-timates also re-enforce the fact that you will be working on discrete chunks of work at a time, which should help you cope for descoping of functionality by the development team.

The speed of change is what makes Agile development so popular. If Agile development is the speedboat, the more traditional development approaches are most definitely the oil tanker. Slow to get moving, and hard to stop if a change of direction is needed. Understanding how the work breaks down, and writing in a style that helps encourage and support that, you should be writing discrete chunks of information that can be used anywhere.

In other words, you should be writing as if you are in a single source environment, even you don’t have a database or CMS in place, even if all that content is being held in one document. The principles and structure that single source systems promote will allow you to keep pace with development.

Be the speedboat!

“Don’t know what I want, but I know how to get it”
Jeff Patton revisits the basics of Agile development, and one section leapt out at me.

Saying “shippable” to people in the customer role means implies they’d better get the requirements right because that’s the way Agile development works.

Now, I believe Agile people had something else in mind when they said it. I think they mean keep code quality very high. Keep the code supported with unit and acceptance tests. Take steps to validate each and every user story. It tells testers to get involved earlier and more continuously. It tells developers to develop with a higher attention to quality. (Apparently developers would be developing crap otherwise?)

Which is all well and good, but isn’t there something missing? Hello? Product Documentation?? Regardless of his omission (an oversight, I’m sure) If you are involved in a software team using any form of iterative, Agile development then give it a read.

Collison’s Ignorance Spiral
After every release cycle has been complete, we undertake a Retrospective, looking back at what went badly and what went well, with the aim of carrying forward the lessons learned into the next release. I think we are pretty good at it but some of what Chris says is interesting:

I’ve been in a number of lessons learned reviews where the intent of the meeting seems to be catharsis for the team or compliance with the process, rather than learning for the organisation.

Is that such a bad thing? Sometimes the discussion is more important than the outcome, and if the team needs catharsis then surely it’s better to provide an outlet for it? Admittedly I’m taking what Chris wrote and skewing it somewhat, but he makes some good points.

Top 10 Distraction Stoppers
Nice list of useful applications, particularly item 5 “Minimise your Word Processor”. One of the commenters suggested an application called q10 as an alternative to Darkroom for Windows.

I’ve been trying out q10 recently, mainly for the posts on this blog and for an article I’m currently writing, but I’ve slowly been extending it to other things and I have to say it is very effective. It takes a bit of getting used to but if you have problems focussing on your writing, and I mean REALLY focussing, then it might be worth a look.

Project Blogs, Email and Dual Collaboration Channels
Written in response to a separate post, this paragraph leapt out at me:

A larger question is how to efficiently manage processes that, for historic or practical reasons, require collaboration among multiple communities that maintain a mix of potentially incompatible formal and informal communication processes.

It’s something that we repeatedly visit at my place of work, we have a very successful wiki, and we’ve started to ponder if there are other tools out there that might benefit us in other ways.

In my head there is a need for something like Twitter but with the ability to post slightly large amounts of information (not much, say double the character count). That way anyone can post a quick thought for the consumption of others. Very informal but possibly a good way to capture the myriad of ideas that are generated each day?

What of agile documentation?

It seems like such an old argument that surely, SURELY, doesn’t need revisiting? Alas it seems that the world of software engineering still contains those who think that code = product. Thankfully, in my experience, the numbers are thinning as most practitioners of modern software practices are at least educationally aware of the need for product documentation, even if they don’t fully understand the reasons. However, there are still those who are happy to hack away, and then claim they have a product. If you are such a person let me make one thing clear, you are wrong.

Not only are you wrong but as time marches on, you get further and further from being correct, all the while creating further problems for you and your product.

Just over a year ago, in preparation for my new job, I spent sometime reading up on Agile development and in particular I focussed on Extreme Programming (XP). The more I read the more I came to realise that this was an area which was popular with developers, yet had little to no mention of product documentation as a fundamental part of the methodology.

Mention of unit and acceptance testing as fundamental parts of working in XP suggested there was at least an understanding of the importance of solid, well constructed tests to help make to a “better” application (test-driven development) but the more I read, the more I become slightly disconcerted at the lack of consideration given both to the production of product (end user) documentation or of the benefits and skills a technical writer can bring to a development team.

Truth be told, I’ve still to find more than a passing reference in any of the more recent publications and articles I’ve found but I’m happy to be proven wrong. Perhaps I’ve been reading the wrong things, and visiting the wrong websites? Or, more worryingly, perhaps there really isn’t anything out there.

Obviously, as a technical writer, the role of product documentation as part of the product is something that is at the forefront of my mind, and I’m not expecting any software engineer to have to worry about such things beyond understanding that we are a fundamental part of the product offering and hopefully agreeing that there is a level of expectation setting to be undertaken.

That said, I do expect a software engineer to understand that software without any support, be it formal documentation, training, or a dedicated support team, is NOT a product. If we can’t agree that fundamental trait then perhaps that problem requires a solution (thankfully, as I said earlier, I don’t think it’s a huge issue at present).

Quite simply, products include documentation, support and training, and tell a cohesive story to a potential buyer. A story that says, yes this product will do X, Y and Z, and if it breaks we’ll do our best to help fix it, and we’ll support you as you learn to use it throughout the lifetime of your relationship with the product (and, therefore, the company).

Admittedly the lines are blurring, with better UI design there is less need for the end user to head to the documentation for assistance but I’d argue that, conversely, as UI design improves and more people become aware of the basic principles of software applications (we all know cut and paste by now, right?) then the end users will start to stretch the applications in ways that hadn’t been considered and it is at this point that product documentation (information) becomes the key differentiator between products.

Of course it is possible to happily exist as a technical writer in an Agile world, but I think we need our voice to be louder.

So I guess my question is, who is willing to shout?

Note: I am aware of Agile Documentation, but I’ve yet to read it. It seems to be more focussed on a developer writing documentation though? I’ll post a review of the book soon.

“There is no such thing as too much information”

We’ve all heard this statement at one time or another, and in the internet age it’s accepted as a statement of truth. Which is shame as it’s completely wrong. Turns out, that you only need enough information, not all of it.

A while ago I wrote up some thoughts on how to integrate an authoring team into an Extreme Programming (Agile) development group. The post Trickle vs Traditional outlined a basic way of building up the required content throughout the various stages of an XP release and, to save you re-reading that post, let me grab the crux of what I was saying:

The trickle method relies on the ability of the technical author to retain a “big picture” view whilst working on multiple chunks of information at any one time. The information will not come in a set order, nor from a definitive source, instead it will trickle in from various parts of the development team, testing, and so on. Your job is to monitor the flows of information, position yourself within a stream (or two) and divert the information you need into the documentation.

In reality this means that you need to develop a good technique for filtering information, knowing when and what to leave out of the documentation and relying on your knowledge of the product to help you make decisions and make them quickly.

Quite simply, to remain agile in such a system you need to be able to make decisions. A decision can be wrong, as long as you make the decision to fix it as soon as possible.

In a way, you start to write by instinct, trusting that you properly understand all the myriad of factors that influence what information you are creating and letting your talents as a technical writer take over. As Malcolm Gladwell, who wrote an entire book about this type of decision making, suggests:

We live in a society dedicated to the idea that we’re always better off gathering as much information and spending as much time as possible in deliberation. As children, this lesson is drummed into us again and again: haste makes waste, look before you leap, stop and think. But I don’t think this is true. There are lots of situations–particularly at times of high pressure and stress–when haste does not make waste, when our snap judgments and first impressions offer a much better means of making sense of the world. [source]

All of that sounds slightly scary if you are currently working in a process-heavy environment, with requirements and specification documents been seen as a way to provide all the information everyone needs, and which are typically a rather slow cumbersome way of handling information.

Anyone who has written such a document knows how hard they are to do as you can’t know everything at the start of a project and over time things change. Having previously worked in ISO regulated companies, where the audit history of a document was almost more important than the information in the document itself, I know how onerous, time-consuming and false those systems can end up being. Many is the time when everyone in a discussion knows what is going on but you still have to write it up, review and approve it, before it can be officially logged in a system that is rarely referenced.

Monitoring the flow of information, trickling it into your documentation as and when needed, making quick decisions and trusting your instincts certainly feels like a more natural way to work. It does mean that there is no such thing as a final document and there is a chance you will publish something that is wrong; yet it is the very possibility of that happening which keeps itself in check. Allowing people to make their own decisions instills a higher level of professionalism and lowers the number of errors.

It’s not suitable for everyone and some industries wouldn’t enter it but it’s an interesting way to work. Limiting the amount of information you have available, and making decisions based on those seems wrong but it does work. You just need to be brave.

Can’t recall where I saw this but it struck a chord so I grabbed the main tenets with a view to expounding on them at a later date.

However, as simplicity suggests, I really don’t need to bother.

• Because there is complexity in purity.
• Elegance in plainness.
• Intricacy in streamlining.
• Richness in reduction.
• Depth in minimalism.
• Surprise in uniformity.
• Innovation in re-use.
• Cool in the avoidance of cool.
• And there is true sophistication in simplicity.

These were not written about Technical Communications but they might as well have been. I’m seriously considering printing these off and pinning them up on the wall.

I’ve spent the last couple of days writing an article for an industry magazine. It’s not something I’ve done before and I thoroughly enjoyed the challenge. It was aimed at CEO/CFO level, so was heavy on business aspects and lingo, not something I’m comfortable writing to be honest, I prefer plain english.

However, what really surprised me was how quickly I got into the mindset and soon I was “dynamically leveraging” and “interactively promoting” all sorts of things. Now I need shake myself to make sure it doesn’t creep into my normal technical writing.

Still, it was an interesting exercise and the skillset is the same, it’s only the language that differs. I still needed to write with the correct user in mind, needed to phrase and structure the information in a way that makes sense to them, and I needed to pitch the technical level of the article correctly.

Of course, as the article is for a magazine, the tone could be a little lighter and it was fun to experiment with this. For example, I opened the article with a first-person scenario which although I’ve been writing a blog for a few years now was still a challenge, for this humble technical writer!

I’m waiting on feedback from the PR company, but hopefully it’ll get published. Fingers crossed.