Archive for Technical Writing

10 Oct 2012
Agile Development • Technical Writing

The Agile process and its affect on persistent documentation – a work-in-progress or overlooked aspect introducing long-term risks?

FrAgile documentation

Over the last few years Agile development has become the benchmark of progressive, bleading edge software development. The idea is to produce working software within a very short space of time, then build on that in subsequent deliveries. As a concept it works very well and brings many benefits:

  • the customer sees working functionality very early in the development process and become part of the development team. Rather than signing off a specification then waiting months or years for the functionality (during which time requirements more-often-than-not change or develop) – the customer becomes an integral part of the development team and process.
  • changes can be accommodated as the finalised functionality is not fully designed at the start of the process. The business requirement may be known but the intricacies of the functionality to meet that business requirement are developed, holistically, as the functionality itself develops. Changing requirements can be absorbed by this flexible approach without the need to stop and re-spec.

I have seen the good and the bad of Agile implementations.

The benefits were clear when, within an organisation in which I worked, Agile was trialled with a single team working on a single product release. The team were corralled together and had all the required expertise gathered in one place. We were focussed on a single product delivery with customers close-at-hand providing us valuable feedback throughout the development process. It turned out to be a perfect situation for Agile development and worked tremendously well.

I have also been a single author (or the lead of a team of two) providing the documentation cover for multiple Agile development (and Maintenance) teams. This was a nightmare as not being a part of any one team made it incredibly difficult to keep up-to-date with multiple fast-paced, changeable developments.

One statement in the Agile Manifesto’s statements has raised, for the Technical Author and others working within Agile teams, some interesting issues. The statement is:

Working software over comprehensive documentation.

When I first saw this statement I was under the impression it meant the removal of the full specifications drawn up under waterfall-style processes, or even the project-management type full project planning artefacts because, under Agile, planning is performed in short sprints (two weeks is the norm) and the functionality develops holistically over time.

I have seen this statement used by Agile projects to protect themselves from producing little, if any, supporting documentation. This becomes a ticking time-bomb as those with the functional and coding knowledge leave the institution or move to different areas of the business.

There is a time and a place for Agile. When implemented properly is an exciting, fast-paced development methodology that can reduce design and development times and result in a product that more closely meets the customer’s needs when it is delivered an implemented.

Done badly – it’s a confusing, lonely place for an author to be. Quickly developed functionality with very little supporting documentation can quickly get away from you if you have your eyes (and typing fingers) busy elsewhere. If you are not an integral part of the Scrum team product, you better have (or build) very strong connections within the analyst, development and test teams because you are going to need them!

Further reading

A recent discussion on the ISTC Discussion board on LinkedIn titled ‘Tech writing using Agile – why are there no benefits?’ struck a chord within me as a number of authors raised the very same points that have kept me awake (at least twice!).

Sources

What do you think?

Do you have an Agile success story or nightmare to share?

Have you worked with multiple scrum teams simultaneously? How did you juggle the needs of multiple teams?

What do your scrum teams produce in lieu of upfront functional and technical specifications to ensure your systems can be understood?

 

Rob Allison | No comments | Tags: ,
10 Oct 2012
Technical Writing

Serendipity and three months in the sun…

Across the bay at The Pearl, Doha, Qatar

ser·en·dip·i·ty

[ser-uhn-dip-i-tee]

noun

1. an aptitude for making desirable discoveries by accident.

2. good fortune; luck: the serendipity of getting the first job she applied for.

I have not been on for a while (apologies for that) as I’m currently working in Qatar. After 12+ years at my former employer I had the good luck to be offered a contract position, here in the middle east, creating E-Learning, classroom training materials and later – possibly delivering the training for the support systems being installed in a new hospital being built here.

I’d only put my CV online for a couple of weeks – and was really only testing the water – when after a quick phone call from an agent based in Dubai, a whirlwind week of Skype interviews and a quickly arranged wedding (I’ll explain later), I found myself on a plane heading East. It felt like serendipity was with me so I took the opportunity and here I am! A new job and a title for this post.

After being here for almost three months and having now adjusted to the sun and life out here in a muslim country, I feel able to pass comment on life and work out here.

Here’s a couple of pics to give you a flavour of my location. Over the next few posts I will try and paint a picture of the work, lifestyle and people in this fascinating country.

 

 

Rob Allison | No comments
25 Mar 2012
Careers • Technical Writing

So where are these specialist technical author roles?

When you reach a crossroads, how do you know which is the best way to turn?

With the gentle breeze of change blowing through my employers (its not yet had time to build into a wind since the takeover), I have been taking stock of my position, my goals and begun to look around at what opportunities are out there.

From the discussions I have engaged in on Twitter, Linked In and around the blogosphere I thought the market for technical authors would be more splintered and I would encounter more opportunities for what I consider to be the current ‘buzzword’ roles than I have actually found. Buzzword roles are those everyone seems to be talking about, those which technical authors could/should perform well in. I’m thinking of:

  • Content Strategist
  • Information Architect
  • Content Curator

One of the major employment websites in the UK returns the following numbers of open vacancies (posted in the last seven days):

  • Technical Author – 118
  • Technical Writer – 33
  • Content Strategist – 9. Only one of these had the job title of Content Strategist, the remainder had content and strategy within the description.
  • Information Architect – 270. The majority of these were combined with UI or web design.
  • Content Curator – 0.

The good news is there seem to be jobs out there. My initial findings are positive and there are a couple of positions that caught my eye. All I need do now is practice my interview technique. It’s been a long time!

Maybe I wont go in for a complete change though

I was commenting to a friend that technical authoring jobs in my part of the country seem few and far between which means either moving home (which we had done a couple of times before my son came along but would now be so much more difficult) or long commutes (expensive and tiring). I was musing about what I could do should I decide to change direction. Her responses: comedian or life coach. I’m not sure if she meant my life to date is a joke or puts me in a position to offer useful advice to folk – I dare not ask!

 

Rob Allison | 2 comments
12 Mar 2012
Technical Writing

Waterstone’s drop the apostrophe from their signage – the end is nigh!

Waterstone's shop signage

Soon to be historic Waterstone's signage

The bookseller Waterstone’s is to become Waterstones.

The apostrophe being dropped, they profess, makes the company’s trading name more practical and versatile in a trading world of URLs and email addresses.
This decision has been met with howls of derision from the grammatically sensitive. The Twitterati waded in with the hashtag #isnothingsacred to vent their anger over the planned change.

A piece on the Telegraph’s site contains the following fantastic quote from the chairman of the Apostrophe Protection Society:

John Richards, the chairman of the Apostrophe Protection Society said: “It’s just plain wrong. It’s grammatically incorrect. If Sainsbury’s and McDonald’s can get it right, then why can’t Waterstones. You would really hope that a bookshop is the last place to be so slapdash with English.”

The press have also been quick to devote columns to the issue of the soon to be dropped apostrophe, its ramifications to grammar and English, and even if Waterstone’s move is indicative of the dumbing down of the English language and our application / appreciation of it.

I agree that a retailer who peddles the written word should be a proponent and protector of the basic rules of grammar. In protest – I’ll never buy a grammar guide from Waterstone’s again.

Having said that, it is nice to see so many people notice and get riled at the amendment. That alone proves there remain a healthy number of pedants out there. Plus, reading the comments written on The Telegraph and Guardian website is good for a giggle or two.

Enjoy:

What do you think?

Does it matter that a fast food retailer employs a better use of grammar than a book retailer in its signage?

Should the rules of grammar really be applied strictly to a company’s name and signage?

Should we care? Language is constantly evolving and the apostrophe seems to have stumped most, greengrocers at least, since time immemorial.

I have just noticed that my spellchecker does not like Waterstones either.

 

 

 

Rob Allison | No comments
29 Feb 2012
Technical Communications • Technical Writing

No 1 laid back career. Really?

Number one laid back career. Really?

The title of Tom Johnson’s latest post on his blog ‘I’d rather be writing’ grabbed my attention for a couple of reasons.

Check it out for yourself: Incensed at “Laid-back” Categorization of Technical Writing Career.

Firstly, Tom is normally such a laid back fellow that the thought of him being incensed at anything immediately caught my attention. The remainder of the title ensured it was a post I would read. Tom was responding to an article on Yahoo careers, 5 Low-Stress Career Options, which places technical writing in the number one position for laid back careers. Not top ten, not pushing for a podium position but top dog, numero uno, the big cheese in laid back career choices.

If this is true I need to look at my employer, every previous employer, the way I approach the job and how my peers approach the job.
I was so taken aback with the article’s angle that I performed a quick straw poll around the office and at home to test how others see my profession:

  • What do you think is the most laid back career? Responses:
    • Artisan / craftsman
    • Aromatherapist
    • Road sweeper
    • Masseur
    • Gardener / Park Ranger
    • Stop/Go sign operator on an Aussie motorway

So no technical writing jobs in the laid back career list or anything approaching a technical author.

  • Describe the role of technical writer in a word or phrase?
    • Demanding
    • Evolving
    • Multi-faceted
    • Cutting edge
    • Useful
    • Practical
    • a teacher of teachers and experts
    • Pedantic

Nothing even close to laid back in the role description. So what makes technical writing so laid back to the Yahoo Education team?

Laid-back features: Technical writers, which ranked sixth on CNN Money and PayScale’s list of “10 least stressful jobs”, said they felt less daily deadline pressure because many of the assignments are long term.

Long term assignments? I’m not sure any/many technical writers benefit from long term assignments anymore. In fact, long term assignments are what I do to meet my annual objectives while supporting the business in its day-to-day activities.

For example, try working within an Agile software development cycle where deliveries are made twice-monthly and tell me about long term deadlines.

Try servicing the documentation requirements of a number of Agile Scrum teams whilst providing the release documentation support to a Support and Maintenance department. Long term assignments? I wish…

Tom may be incensed. Personally, the article left me speechless. Having now read the article a number of times, forwarded it on to peers and colleagues and seen their feedback all I can say is I don’t see my role reflected in Yahoo’s piece.

If anyone has one of these laid back technical writing positions please let me know. I’d love to hear about any companies with such a vacancy. For that I’d be willing to change my mind!

Rob Allison | No comments | Tags: ,
« Older Entries