Tag: XP

My PC



ss001, originally uploaded by Gordon.

Since I was asked, here is my current Windows XP desktop.

I keep the desktop clean, it’s my “inbox” where things are then filed or moved. The taskbar fades out when the mouse ISN’T over it, and yeah Xentient Thumbnails to get the icon of an image to display as the image itself (a la the icon on my desktop).

No Docs = No Product

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.

Trickle and Blink

“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.

Write 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.

Dilbert does it again

I really don’t know how Scott Adams manages to tap into these things, or is the software industry REALLY that similar the world over?

Regardless suffice to say that, in our Extreme Programming (XP) development group (XP is a form of Agile development), todays’ Dilbert raised a bit of a chuckle:

(click for bigger)

Trickle vs Traditional

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.

Small things matter

I’ve been pretty good about not fawning over my Mac too much, right? I mean this hasn’t turned into a fanboy style homage to Steve Jobs and all things Apple. Well, no more so than usual… I don’t think.

This does mean that I’ve had to fit the strong urge to blog about the myriad of small things that I’ve noticed when using the Mac, the myriad of things which go to show that attention to detail and spending time on small issues IS important. Of course the fact that the Mac software is pretty robust in the first place allows the developers at Apple a little more time to worry about such things but that just means that it’s good for the user.

There are many little things that make using a Mac fun. They are all simple and some would say pointless, but watching the screen rotate like it is on the side of a cube, spin round and stop at another desktop (when switching users) may not be necessary but does add to the overall experience.

As I say, I’ve not mentioned most of these as many other people have waffled on about them at great length.

But last night was the straw that broke the dromedaries back.

There are two user accounts on our MacBook, one for me, one for Louise. Similar to Windows XP you get a login screen when you first startup the Mac and as it is a laptop we have passwords on the logins.

Last night I was half watching the football, whilst the laptop started up, so wasn’t really paying attention when I typed in my password. It was then, with a sense of some disbelief that I saw the login screen shake its head at me.

Yes, that’s right. When you enter an incorrect password, the login screen shakes from side to side briefly, just like it is shaking its head.

Intrigued I entered another wrong password, and watched it again, and after the third try was even more impressed when the password reminder I had entered when I created the user account slide into view under the login screen.

THAT is attention to detail.

Yes a simple “sorry that’s the wrong password” message would do the same but that’s what makes using the Mac much more fun, much more engaging. I know the naysayers will say “but it’s a computer, it needs to be functional” and as I’ve said before, if that’s the way your mind works then fine. But you are missing the point, and no amount of explanation is going to convince you. Am I right?

On switching

I received my MacBook some weeks ago, but decided not to post immediately and try to get a better feel for both the new hardware and operating system before posting my thoughts. What follows has been written up over the period of a few weeks.

It’s official. I am now cool. I must be because Matt said so, in a roundabout way admittedly, and in case you have no earthly idea what I’m blithering on about now, I’ll first refer you to this post, and then get to the point and confirm that yes, I am now the owner of a shiny white MacBook. I am cool.

As is my wont, I had spent some time researching, reading articles written by those who had ‘switched’, and compiling a small collection of free applications that I figured I’d need at some point. So, with several PDFs, a folder of software, and several AVI files (for watching on the plane), I was all set.

There are a myriad of articles and blog posts written about switching from Windows to OSX, and I’m not going to add to them, instead I’m going to attempt to give you how I feel about becoming the owner of a Mac, because that’s what it’s really about, isn’t it?
Read More

XP tip

Quickly Tiling Windows in XP
“With the first window open, press and hold Ctrl, then right-click the second window’s button in the taskbar and choose Tile Horizontally or Tile Vertically in the pop-up that appears.”
You really do learn something new everyday, thank you LifeHacker!