bookmark_borderWrite the docs first

I’m currently pondering a proposal, suggesting to our Dev team that we write the user documentation first, and then use that as the basis of what the product should deliver.

This wouldn’t work for everyone but given that an XP environment encourages little (well, less) documentation than a more traditional ISO style project, then having a draft of the user documentation would be beneficial in many ways:

  1. Early design thoughts are often lost as they are translated into the stories used to develop the functionality. Fleshing these out into more fully formed documentation would better capture that information, and focus it on the user.
  2. Earlier consideration of the “what ifs” will likely come of this, pushing thoughts and discussions out into areas that the documentation needs to cover but which might not be considered as they might not be part of the software.
  3. Focussing on the final product, rather than just the next piece of functionality, should make the big picture easier to see, allowing the developers to better understand WHY they are working on a particular piece of functionality.
  4. Testing/QA can use the documentation to validate the software that is being produced. If it doesn’t match the documentation, it’s wrong.
  5. Anyone coming late to the team can get up to speed much quicker.

I’m still thinking this through, and by pushing on with the documentation, sometimes even striding ahead of development, the technical author can help with the finer details of the implementation, running through some of the scenarios (or edge cases, or “unhappy path trails” depending on your lexicon) before they have been approached by development, blazing a trail for them to follow. After all, we spend a lot of our time considering things the readers of our documentation are likely to ask, if the answers need to come through the software then what better way to develop the solution?

All of this would, of course, be in close consultation with the development team but I think it might be an interesting experiment to try.

Anyone got any thoughts? Pros? Cons??

Update: I posted about this on the TechWR mailing list, and Andrew Warren pointed me at his previous response on this topic. Interesting.

bookmark_borderStress is a wonderful thing

Nearing the end of a project is always a stressful time. Regardless of the best plans, contingency and prayers, things always end up tight at this point. That’s when the stress kicks in.

I actually revel in this kind of work, doing my best stuff under pressure, with no time to ponder I make decisions with conviction and plough onwards. There is also a subtle effect on other areas.

I’m usually working long hours at this point, and so end up a little run-down, narky and tired. Emotions of all kinds are quick to the surface and over the years I’ve started to focus more on them than any impending doom scenarios that are building elsewhere. I should point out that I work in the software industry so, in most cases, missing a deadline is bad for business but no-one loses a life, it’s not the end of the world, so whilst I do get stressed there is a point where I realise I’m getting stressed and I just… well… stop getting stressed. Hard to explain and it took some amount of time to get it sorted in my head.

Anyway, whilst I’m in this zone I try and focus on the positives and one always comes shining through. Louise. She knows how to handle me at times like these, and it makes me appreciate her all the more.

In addition, with emotions wrought and wrangled and because I often resort to headphones to get the last minute of “do not disturb me” time out of the day, I find the oddest songs can develop a strange resonance and catapult themselves into my internally kept list of favourite tracks. Such tracks literally give me goosebumps. Whack on Nothing Else Matters by Metallica and when that guitar solo kicks in… yup, goosebumps.

Sticking with the rock theme, for I cannot lie I do like my rock music, the current song achieving similar levels is the oddly repetitive yet wonderful anthemic Come Alive from the Foo Fighters. Not only does it seem to musically hit the right notes, lyrically it brings me full circle back to the centre of my life, my darling wife. Odd that.

I just wish I could play it just a little bit louder (but I’m quite considerate when using headphones).

Anyone else get this with certain tracks? Just me?

bookmark_borderFree is Free

A few weeks back Radiohead, a fairly well-known rock band from England, released their new album via the web and in a fairly radical move, allowed people to pay whatever price they wanted for the privilege. Anything from £0.00 to £100, they said (I wonder what the top amount paid was…).

Since then… apart from a couple of press releases full of ill-thought out stats… nothing.

What happened? Where is all the noise? Where are the “told-you-so” bleatings? What happened to the “revolutionise-the-music-industry”? It’s a disappointing damp squib if you ask me.

On one side, Radiohead remain silent on the matter. Or as good as.

On the other side the press was quick to report that a large number of people grabbed the album for free. They threw stats out like sweeties; one-third of people who downloaded the album paid nothing, average price paid was £3, and so on.

What does this prove? What does this say? Everything and nothing of course, and part of me hopes that was exactly what Radiohead intended.

Offer something for free and people will take it. Offer something with only guilt as a payment mechanism and many people easily push any emotional feeling to one side and plunge onwards. Offer something which can be free, and people will take it for free. This is the society we live in, writ large and then swept under the carpet.

Reaction to all of this freeloading seems out of place, there was SO much hype, in many different quarters, about this that it seems almost out of proportion.

Other artists (most notably Prince) have given away their music for free, realising that they make the bulk of their money outside of CD sales, but part of me hopes (desperately) that the music-loving fan, when given the ability to set a price, would do the right thing and pay up. A glint of humanity and integrity is all I’m looking for…

How laughable.

What I really don’t understand is where is the backlash? There is no screaming rhetoric to be found anywhere, either bemoaning the freeloaders or angry that this experiment failed to show the music industry that it was a viable solution.

But I guess that is a good thing because this experiment could do no such thing. It couldn’t PROVE either, the freeloaders (statistically) grabbed the music in about the same percentage as they do for music released via a record label.

The music industry didn’t take much of a kicking either as Radiohead will also release the album through a record label and hey, guess what, not EVERYONE is comfortable downloading music. The majority of the music listening public like CDs, or at the very least something tangible.

Reading between various lines, I think the only thing this experiment could ever prove was whether an artist would make more money PER SALE if they distributed things themselves, or via a record label. On that front I think Radiohead, on a per sale basis, doubled their money? I’m not sure as getting accurate figures is proved difficult but they certainly didn’t lose any money.

The deafening silence that blankets this entire episode worries me more than any of the financial/industry aspects.

Are we really so quick to put such things aside? Wasn’t this supposed to herald a new wave of thinking in the music industry, or is that where the silence comes from? A million record industry executives trying to figure out how to ‘fix things’.

This kind of thing isn’t a viable business model for a semi-successful band, one who flirts just below the limelight, and whilst it may boost the standings of newcomers (mySpace in particular) at a certain point it will start to hinder them.

I’m bemused and a little disillusioned. I had hoped this would’ve kicked started… ohh I dunno… something, anything… but nothing seems to have come of this. So I’ve gone back to my usual method of purchasing music and will continue to do so with knowledge of a better way gnawing at my wallet.

bookmark_borderStepping Back

I was recently chatting to someone who has a plan.

He is retiring at aged 50 and going off to live in the wilds of Canada. He’s Canadian so it’s not as far-fetched as it sounds, but the really scary part is that he is deliberately going to be “off-grid”. He’s a self-confessed geek so this is quite a step and, when he told me all this I suggested that it was some form of backlash against the grip of technology, a deliberate swipe at the lifestyle we all find ourselves living in modern society.

“But of course it is” he grinned.

I harbour a similar desire, namely to retire aged 50, but as yet have no plan to get there. It’s unlikely to happen and as such will remain a dream but, it is something I’m now thinking about. If I did retire early, what would I do? Where would I go?

The idea of living remotely appeals to Louise and I, even if it isn’t that far removed from civilisation. Being off-grid, no internet, limited phone access, is another deal entirely but given that I do so enjoy snatched moments of solitude, an afternoon lost in a book, a stroll round the park, it is worth considering.

Personal space is something for which we all hunt, something we aim to manufacture by donning headphones and blocking out the rest of the world. Regardless of where we are, the message remains the same and annoyance comes from those that don’t even realise that is the aim. It’s not just about listening to music, it’s about creating a place that only belongs to me. It’s most significant when wandering city streets to your own soundtrack, the reverie snapped by Big Issue sellers and small women with big umbrellas. Elsewhere this method of isolation can be more reliable yet the one place where I could be assured of true solitude would be at home and I rarely, if ever, use headphones there.

Perhaps true solitude is only possible when you are in the middle of nowhere, for any manufactured space bears the scars and remnants of modern day living. At home the phone demands an answer, walking down the street you are considerate of others as you navigate the myriad of shoppers and so forth, even lying in the park on a summer day is fraught with stray dogs and misplaced footballs.

I treasure quiet moments. Snippets of a day to pause and reflect before returning to the headlong plunge of life. Some people enjoy the helter skelter existence we seem to have these days. The incredible rush of even the most basic day is at times a sad indictment of our society, at others a thrilling embracing of being alive. Recharging our batteries is reserved for sleep, yet surely there needs to be more, surely we must pause more often to gather ourselves before the next onslaught?

Those that retain the ability to stepback have a skill to envy. One simple step creates the space I crave yet can so rarely find.

I need to learn to step back now and again.

bookmark_borderRecently Read

With the TICAD conference last week, a couple of days in my sick bed, and the imminent product release I’m working towards, I’ve not had a lot of time to post here. However, the RSS feeds keep trickling in, so here are a few items that caught my eye over the past couple of weeks.

What Beautiful HTML Code Looks Like
I’m a terrible coder. Which is just as well because I’m not a developer but as I do dabble in HTML and CSS quite frequently (hey, and PHP too), then this is a good reminder for me to develop my own best practises.

Code is Tabbed into Sections: If each section of code is tabbed in once, the structure of the code is much more understandable. Code that is all left-justified is horrific to read and understand.

Includes a neat infographic, downloadable as PDF, which is now pinned beside my desk.

Procedures: The Sacred Cow Blocking the Road
An update on a (yipes) 10 year old article. I don’t think I read it when it was first published but I have read it. Well worth another visit though.

“It takes a surprisingly short amount of time for a user to feel unstuck. When I was a usability consultant, I used to advise clients to put the critical information in the first three words of a sentence.”

IA Deliverables
From Content Surveys, to wireframes, Personas and Use Cases, a brief overview of each is followed by a sample template. Not only a useful resource but a good overview of the typical process an Information Architect will undertake, a lot of which can be adapted to more traditional product documentation.

Collaboration is not a dirty word
Collaboration on content (not documents, even if that is where the content ends up) was a key part of my presentation. It’s good to see the switch from document-centric to info-centric taking place.

I love things being this easy. I love getting (almost) zero emails with attachments. I love not having a hard drive full of Word documents.

DITA Troubleshooting specialization

The Troubleshooting specialization creates a new topic type that is well-suited for problem-solution information.

7 Ways to keep the post-conference buzz
Not long back from a conference myself, I have already done a few of these things (item 3 in particular) but some good ideas here.

Wikis for Documentation?
Steve Manning isn’t sure about using Wikis for Documentation but does think they could be a big hit in another, related area:

Most writers have to guess about their users. Few writers get the opportunity to speak directly with users. Few get any sort of feedback at all. They are left to do their best. How useful would it be to be able to post your document on a Wiki and have users be able to comment topic-by-topic? To see the questions they ask?

I totally agree. All I need to do is figure out how this works within a single source environment, and tackle a few issues around governance and change management and it could be an excellent working model.

And finally…
I’ll be updating the TechComms RSS feeds download soon, so if you think you should be on the list (or even if you aren’t sure whether you are or not) then let me know. It includes all kinds of stuff which is loosely related to Technical Communications, and I’m always on the lookout for more sources of inspiration. Leave a comment if you think of anything.

bookmark_border(Don't) Call me

I need some advice. I want either cheaper TV, Broadband and Telephone calls, how do I get them? Actually that’s a lie, I only really want cheaper telephone calls.

Currently we have contracts with both Sky and Virgin Media.

We have Sky for our TV viewing and we take all the movies and sports channels, although I am considering cropping the ‘standard’ channel package down a little. My parents have Virgin Media for their TV service and, ignoring the fact I’d have to invest in a PVR system of some sort to get back the functionality I’d be losing, I happen to think the Sky service is better. It certainly seems easier to use and Virgin don’t give you the choice of what to record (hence the separate PVR).

We have Virgin Media for our telephone line and broadband and, from what I’ve read, the Sky broadband service isn’t the greatest and I’m loathed to move from Virgin Media (was Telewest) as the broadband service has been solid and reliable for the past 6 years, and we DO spend a lot of time online (Louise increasingly so). The telephone line is… well it’s a telephone line. We have caller ID and cheap(ish) calls to Europe.

We both have contract mobile phones, and once my contract (with Orange) is up I’m considering moving to PAYG… but in saying that I do miss not having a good phone with internet access and reliable Sync with my contacts… so I might hold out and aim for one of the HTC devices (running Windows Mobile). I am currently reducing my contract at every opportunity.

Basically, given my reluctance to switch broadband and TV suppliers, then the phone service is the one I’m focussing on. Largely our phone calls are within the UK, bar two or three calls a week to Spain.

I’ve done some digging in various forums and websites and think I know the answer but thought I’d see if my wonderfully intelligent readers could offer me another insight.

Given the restraints, what is the best phone service for us to switch to? Should we just ditch the landline altogether? What is the impact on people calling us (actually that’s a moot point, both mobile phones have very poor reception in the house so that wouldn’t be practical)? Do I need to do some more research into VOIP?

And yes, I am one of those bloggers who has just received a months trial with a Skype mobile. So that may be an option I can explore.

Any further comments, thoughts and suggestions are welcomed. Or should I just shut up, because, frankly, this isn’t that big a deal really.