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.

I started this blog to have a separate place to write about my “professional” thoughts and I guess I thought I could maybe add a little value to the cluttered world of technical communications, or at the very least raise my profile a little. Yes, I have an ego, but it’s kept in check for the most part.

However, like my other blog, the main reason this blog exists is to give me a place that I can consider and process my thoughts. I’ve always found writing things down helped me get a good sense of what they were, even if I didn’t necessarily start with a cohesive picture in mind. Sometimes the simplest issue, one that has eluded me for some time, leaps into focus when I start writing. I’m not sure if it’s always been that way or I’ve now trained myself into such a habit but I’m not complaining, it works for me and I’ll admit that I still get a little buzz when something “clicks”.

If I were in a cartoon a light-bulb would *plink* into existence above my head when that happens. Reality can be such a disappointment.

Today brought a good example of such a moment and rather than deleting my thoughts, I’d thought I’d post them here. Sharing is power after all (badly paraphrasing remains inexcusable).

One continuing theme on most of the mailing lists I follow and in various blog posts across the land, is that of knowing your audience. Knowing why you are writing, and who you are writing for are the fundamental tenets of our profession. They are so fundamental that, if I’m honest, the incessant reminders about them do start to grate somewhat. After all I’m a professional, how many times do I need to be told to consider my audience? How many times do we need to restate something we all know and understand.

I’m happy to admit that some will know more about their audience than others. Some will make do with a rough approximation of what their audience expects, whilst others will interview and analyse their customers and gather requirements and direction directly.

Regardless of your level of commitment to understanding them, anyone who is writing must (surely) consider their audience. Yet, at every turn, the answer to many questions all stem from that presumption, and are presented in simplistic terms. Know your audience they say. OK OK, I get it!

The thing is, after reading such a response for the umpteenth time it suddenly struck me that yes, we do need to be reminded of this basic fact, time and again.

We all have pressures on our work. Whether those pressures come from commitments made to others, from our own professional integrity, or directly from the customer, they all serve to focus us on the end goal and usually to start thinking in terms of quantity. We know we need to document the new interface to the ACME Widget and when pressure is exerted their is a temptation to take shortcuts, and the easiest shortcut is, by and large, to forget the audience.

The cardinal sin allows us to omit information on the presumption that they will “probably know it”, to structure the information according to UI rather than task, and ultimately to regress to a “if you can click it, document it” mentality. That may be a valid mode in certain circumstances but that will depend upon, yeah you guessed it, your audience.

Audience analysis, the use of personas, call it what you will, if you don’t have at least a rough idea of the type of person you are writing for then why bother? You won’t be structing the information correctly, you won’t be pitching the level of information appropriately, and you most certainly won’t be thinking around the various conceptual models your audience are likely to use and understand. The more you know, the better you can focus your documentation, drilling down into the tasks they need to complete and what they need to know before they begin. The better your knowledge of your audience the more likely it is you’ll produce documentation that they can use.

Put it this way, if you aren’t writing for a specific audience, who ARE you writing for?

Ooops.

I’ve gone and done exactly what I said annoyed me, lectured you all on knowing your audience when you already know that you need to know that. You know?

Next time I read yet another “Depends on your audience” response in a mailing list I’m going to try and remember that advice and apply it to my current work.

Addendum: Charles Cooper has been considering the same thing.

My name is Gordon McLean, I am a Technical Communicator* and I am proud to be a jack of all trades.

I recall once being asked to breakdown all the skills required to be a Technical Writer, and then to provide a list of daily work tasks. The list of skills was to be used as part of a skills/training matrix, and the work tasks were to be mapped to a timesheet system.

At first I concentrated solely on the Technical Writers role, but even then you need to wear a number of hats; researcher, analyst, information architect, publisher, indexer, illustrator, proof-reader, editor… ohh and writer. All of those are unique job roles in some places yet, as a Technical Writer, you need to be able to successfully take on those roles to some degree. In most software companies a large part of the job is learning the new features, and as you have access to early builds, you are frequently also playing the part of ad-hoc tester. Admittedly you are usually only testing one scenario, and that scenario is the happy path that will be documented, but a bug is a bug and that means being able to identify one, discuss it with a tester or developer, or both, and why not log it as well?

If you are documenting an API or developer toolkit then, in those instances, you frequently don the cap of novice developer, asking the questions you expect them to ask, before switching caps to presume the role of an experienced developer and wondering if the information you are providing is too simple for them to use or if, perhaps, the structure of the information needs altered.

You need to be able to talk to developers and so you need to know a little about whichever code language they are working with, that way when they mention methods, you can ask whether they mean static or instance.

None of these skills/roles are the core part of a Technical Writers job, but simply additional strings to your bow. The more you know about everything, the more value you can add, so long as you don’t let that detract from your core responsibility, to provide documentation. However, the more you know about everything, the better that documentation will be and the higher your value will soar.

—

Prompted by The Top 5 Reasons to be a Jack of all Trades

* Communicator/Writer/Author, pick one. I favour ‘communicator’ because I don’t always communicate through writing, sometimes through UI design, sometimes through infographics and diagrams. You get the picture (pun intended!).

My name is Gordon McLean, I am a Technical Communicator* and I am proud to be a jack of all trades.

Working in the software industry, and particularly for a company that has embraced the XP development methodology, I have exposure to, and contact with, most of the other roles in the company. I talk to Marketing to understand to who, and where, we sell our software. I talk to Deployment to understand the real issues they experience when using our software (they are our customers). I talk to Training to make sure we are promoting the same message. I talk to Testing to make sure the bug that I have found IS a bug and should be logged. I talk to the New Feature development teams to understand what they are working on. I talk to the Core team to make sure I’m aware of the myriad of feature requests and bugs that they are fixing, and whether they impact the documentation. I talk to our Support team to understand the common issues being found. I talk to the Architects and product managers to make sure what we are doing fits with the strategy.

Throughout all of this I must have an understanding of both who I am talking to, and what concerns them on a daily basis. I need to know enough about how Marketing and Sales work, what languages the Development team use, and know the business reasons behind why a particular piece of functionality is being implemented, and throughout all of those discussions I have to remember my role, and consider how the information I’m receiving in the discussion may impact the user and, therefore, the documentation.

Frequently I find myself to be the cog that transfers a snippet of information from one area to another. A minor bug fix that relates directly to a new feature. Most times those links are known, but on occasion they are only discovered when one of my team has started to consider the documentation requirements in that area.

Talking to all of those people, these different professions has helped me understand my role, and re-enforced my belief that, whilst writing documentation remains the core part of my job, a large chunk of our value comes from making, and maintaining, those connections.

Perhaps Technical Communicators are the social web of the workplace?

—

Prompted by The Top 5 Reasons to be a Jack of all Trades

* Communicator/Writer/Author, pick one. I favour ‘communicator’ because I don’t always communicate through writing, sometimes through UI design, sometimes through infographics and diagrams. You get the picture (pun intended!).

I’ve been chasing this train of thought for a while now and decided to start writing my thoughts down in the vague hope that they come together in a way that makes sense to others. It seems to make sense to me but, as yet, there are a few grey areas into which I may stumble. So, not so much a train of thought but a car crash of ideas, if you will.

Shoddy metaphors aside, the main crux of my thinking is based in my efforts to find a central point around which I can arrange my knowledge. Obviously my knowledge of some areas is greater than my knowledge of others, but part of this exercise is to start to identify the areas in which I’m lacking and so allow me to investigate them further, to feedback into my train.. no.. car… umm, driveshaft??

OK, let’s start over.

The role of a technical writer is fairly varied, and merrily traipses through several distinct fields. Most technical writers will know a little (or a lot) about many topics, how to structure information or how to create a usable index, they will be also have some knowledge or awareness of, for example, typography and readability issues, they will have some knowledge of working with graphics, and they will also gain knowledge of the various tools they use. Suffice to say that the skill set and ‘earned’ knowledge a technical writer posseses is almost endless.

And that’s all before you consider how much they know about the products that they are documenting

So from that starting point we can see that technical writers already dip their toes into various pools of expertise.

Now, let me just changes hats for a second… right. I am now a web designer.

Look at the knowledge I have attained as a technical writer, with a web designer hat on, there are a lot of parallels. Some are direct, some not so obvious but still discretely linked, after all, regardless of the medium the two disciplines share key facets of importance; content and audience. The delivery mechanism is secondary to those at all times.

Web designers also span several different fields, with some knowledge of HTML, CSS and other languages (usually text based), they too worry about layout and typography to ensure readability is maintained, they plan what type of content will be created, and understand the need to structure that information in such a way that it is explorable. The parallels are many.

So, somewhere in my head I’m wondering why the two disciplines don’t seem to be talking to one another. Is it lack of visibility? Is it just me that thinks it is this way? Are there secret meetings going on as I speak?

One of the reasons I ask is because there is a wealth of information out there that focusses on web design, even spilling over into the social/community aspects of information sharing, which the technical writing world could use and leverage. Have a look at some of the articles on A List Apart, for example. Those which aren’t specifically about code tend to talk in terms of analysis, planning and design. All things I do as part of my job as a technical writer. Boxes and Arrows takes you into Information Architecture territory, with user experience key and, for many of us who work in software development and who can influence both the UI and the Use Cases that help constitute a software application, there is a lot of useful information that we can adapt for our own use.

The following is taken from current experience, fitting a Publications team into an agile (XP) development methodology. It’s very much a work in progress…

~

In a more traditional development environment, there is likely to be specifications and design documents on which you can rely. This is not the case in an agile development environment, with requirements focussed around user acceptance, and a heavy reliance on word of mouth (through pair programming) and shared knowledge. It may sound chaotic, it is not. Each piece of functionality is assessed and if there is not a direct requirement for a piece of functionality it doesn’t get done, similarly each piece of functionality is stated as a story, and will have an index card created which can be used to track the story through various stages.

To match the pace of software development, the Publications team needs to adopt a similar approach. Rather than waiting on information to come to us, we need to be involved, engaged and pro-active in learning and understanding what we are documenting, and breaking out of the old authoring model.

Previously large chunks of documentation were written by the same person, often at one sitting. You’d outline a chapter and start bashing in the words, investing a lot of time and effort into your ‘baby’. That concept is no longer applicable.

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.

As such, the technical authors will be sat within development teams and are expected to attend all designing and planning meetings. Understanding as much of the work as possible, as early as possible, will benefit the documentation, and having a technical author in place at the beginning of the development process will benefit the product. Be the user advocate, keep the tasks they will be performing in mind and strive to contribute as and when you can.

This way of working is different, and does mean you need to adjust your mindset somewhat.

You will not:

• Be able to write entire sections in one go.
• “Own” the document you are working on.
• Always finish what you started (but only if it’s planned that way!!).

Hopefully this new approach will make us much more involved in the day-to-day development of the product, and by bringing additional benefits to the development team, will increase our standing with them.