ITauthor

As a manager who never set out to be a manager (but who, nevertheless, is trying to be a good manager) Scott Hanselman's recent follow-up interview with Chris Sells about management struck a chord with me and I wanted to share it.

Among the things Scott and Chris discuss are:

• Being an advocate for the people you manage
• Getting things done means ignoring emails ("At Microsoft you either write code or you delete email")
• "No meeting Wednesday"
• Weekly or daily task setting and progress reporting
• Prime motivators for getting things done: shame and fear

Chris talks about Scott reduced posting to Computer Zen since becoming a manager. I think what he's saying is: you can be a good manager, a good website contributor, a good husband, a good father - but you only get to choose one of the above.

I'd like to think that's not true.

Please note: This video is from Microsoft's Channel 9 website and (I'm guessing) is the copyright property of Microsoft, or maybe of Scott Hanselman. Go to the original page on Channel 9 to see the video in its Channel 9 context, complete with comments.

Other links:

• Channel 9's RSS feed: http://channel9.msdn.com/Feeds/RSS/
• Hanselminutes on 9 Web page: http://channel9.msdn.com/tags/HanselminutesOn9/
• Hanselminutes on 9 iPod feed: http://channel9.msdn.com/tags/HanselminutesOn9/feed/ipod/
• This particular video: http://channel9.msdn.com/posts/Glucose/Hanselminutes-on-9-Follow-up-6-months-later-with-Chris-Sells-on-Managing-People-and-Your-Time
• Scott's audio podcast: http://www.hanselminutes.com/

I've got a MadCap Flare project that I want to publish as open source code for anyone to go and download. It turns out this is extremely easy to do using Google Code. And Google Code has the benefit of allowing you to sync your work with the online source files using SVN (Subversion).

Multiple people can work on the project simultaneously and each time you open the Flare project the SVN plugin for Flare asks you if you want to use the most up-to-date files from the online repository. When you've finished making changes you just commit your changes, straight into Google Code, without having to leave Flare.

Here's how to create a project in Google Code and add a Flare project.

Prerequisites:

• For the initial upload of files into a Google Code project I'm using TortoiseSVN. You can download this from http://tortoisesvn.net/downloads. TortoiseSVN allows you to work with a Subversion repository from the right-click menu of Windows Explorer.
• You will sign into Google Code using a Google account, so you need one of these if you haven't got one already. If you use Gmail you've already got a Google account, so use that.
• You are going to commit files into a publicly viewable repository. Even if you delete a file from the repository, people will still be able to browse previous revisions of the project and view the file. Versioning repository systems like Subversion are designed to keep a historical record of everything that happened to the repository, so there's no easy way to remove all trace of a file that you didn't mean to upload.* So, before adding a project, make sure that you remove any files that you don't want other people to see.

To put a Flare project into Google Code:

1. Go to http://code.google.com/p/support/wiki/GettingStarted and read through the information about project hosting.

2. When you're ready, go to http://code.google.com/hosting/createProject, fill out the simple form and click Create.

   You will now have a Google Code project with one project member: you (or, to be more precise, your Google account).

   You are the project owner. To allow other people to commit changes to the project, you can add more project members from the Administer tab.

3. Click the Profile link (top right of the page).
4. Go to the Settings tab and copy your googlecode.com password.
5. Now go to Windows Explorer and browse to the directory that contains the Flare project you want to add.
6. Within the project directory select and cut the Analyzer and Output directories.

7. Paste the Analyzer and Output directories somewhere outside of the project directories.

   This is to avoid these directories being added to the repository.

8. Do the same to the Project/Reports and Project/Users directories, moving them out of the project for now.

9. Right-click your Flare project directory and choose TortoiseSVN > Import.
   

10. In the Import dialog box, enter the following as the URL of the repository:

    https://<PROJECT-NAME>.googlecode.com/svn/trunk
    

11. When prompted, enter your user name and password.

    These are the user name of your Google Code account (e.g. the bit before the @ symbol in your Gmail address) and the googlecode.com password you copied to the clipboard.

12. Click OK.

    This will now add all of the files/directories to the SVN trunk in Google Code.

    TortoiseSVN displays the progress.
    
    If you have a lot of files in the project this may take some time.

13. When the import finishes, click OK to close the dialog box.
14. Move the Analyzer, Output, Project/Reports and Project/Users directories back within the Flare project directory again.
15. Still in Windows Explorer, in the directory that contains your Flare project directory, right-click anywhere on the background to the main pane of Windows Explorer and choose SVN Checkout.

16. In the Checkout dialog box, enter the URL of the repository:

    https://<PROJECT-NAME>.googlecode.com/svn/trunk

    and the Windows path to the Flare project directory (that is, the directory you just imported into Google Code) as the checkout directory.
    

17. Click OK.

    The files you imported are checked out and marked as under version control.

    A little check mark on the file icon indicates that TortoiseSVN knows they are part of a Subversion repository.
     

18. In your browser, go to the Source tab of your Google Code project.

    For example, http://code.google.com/p/itauthorflare/source/browse/

19. Click trunk and you should see all of the files you uploaded.

    

You can now start Flare and open your project and (if you have the SVN plugin) you will be asked if you want to load the latest version of the files from the SVN repository.

* Note: If you forget about clearing out sensitive files and you discover you've uploaded something you really don't want anyone to see, then you can remove all the revisions within the project - in other words you can empty the project and return it back to its initial state before you imported any files. You do this by resetting the repository.

To do this, go to the Source tab in your Google Code project and click the reset this repository link near the bottom of the page. Be aware that this removes everything from the repository, so you should never do this for a project that has an active community working on it, or a project with any sort of a history because this history will be destroyed by resetting the repository. But if you've just started and then realised there's stuff in there that shouldn't be, then it's a way out of a fix.

In my last podcast I talked about a couple of unscripted screencasts I'd recorded for colleagues at work, to show them how to use some Flare extensions I'd created. My question in the podcast was: is something like this (knocked together very quickly) good enough to put in front of paying customers - or potential customers?

Without seeing/hearing the screencasts it's not easy to form an opinion, so I thought I'd let you have a look. Let me know what you think. Are you put off by the ums and ahs, and the little mistakes I correct as I go along, or does it lend authenticity to the demo? Personally, I wouldn't mind seeing a demo like this as part of the user assistance for a product. I think the effects that Camtasia lets you add (zooming in and the rotating cube effect) lend a little polish to make up for the ad hoc presentation style. But it's probably not everybody's cup of tea. What do you think?
 

 
Please note:  When I recorded this it was purely meant for internal use within my company. However, I've had a look at it and I'm confident it doesn't give away any corporate IP. It does, however, reveal (if you look closely) that I had to Google to find a solution to a buzzing microphone shortly before starting the recording!  :-)

Alternative larger format video  (you'll need to wait a little while for it to download, but the picture quality is better).

Podcast: Play in new window | Download

For this edition of the ITauthor podcast, I just turned the microphone on and started talking. So if ums and ahs annoy you, this podcast probably isn't for you!

I ruminate over whether it's acceptable to use unscripted, unpolished screencasts in published documentation. Does it matter if you stumble over your words once or twice, um and ah, and have to correct your typing as you go along? Does the unscripted approach add an element of authenticity and make the whole thing more realistic and believable?

I also talk about the functionality I've been adding to our Madcap Flare projects to provide alternatives to the built-in glossary popups and expanding sections.

Finally I scan through my iPod and make a podcast recommendation. The podcast I chose was Speechification.
Website: http://speechification.com/
Podcast: http://feeds.feedburner.com/speechification 

 The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

Rhonda Bracey of CyberText Consulting recently wrote a blog post entitled “Documentation: Backup for UI deficiencies?” In the post she quotes an article by Sue Woolley:

Very few people these days will sit down and read a manual for a new software product. The expectation is that we can install software and start to use it straight away. The younger generation in particular is so comfortable with new technology that they dive in and expect it all to work. They explore fearlessly, and are able to master complex hardware and software concepts effortlessly.

If a user has a problem when they are using the software then they will generally either ask a colleague for help or resort to trying to find the answer in the documentation. Typically, they will “dip into” either a manual or the online help and at this point, if they can’t easily find the exact piece of information they need, they will be frustrated with the software.

Documentation is, therefore, rapidly becoming a backup for deficiencies in the user interface and user training rather than a complete solution in itself.

Rhonda asks “Are humans ‘programmed’ to learn by trial and error and not ‘by the book’?” I think she’s onto something. I suspect that over millions of years of evolution a genetically programmed impulse to play around with things as a way of figuring things out has served the human species extraordinarily well. And so today, if given some software (or hardware), plus a set of instructions telling you how to use it, most of us will ignore the instructions and just try to start using the product.

For example, yesterday, for the first time, I was using the PushOK SVN plugin for Madcap Flare to work on our main online help project. My colleague Graham and I were both working on the same project at the same time. He’s been using the plugin for a while and I was on the phone to him asking him questions and we were working things out, in the style of: “Okay, now I’m going to click on such and such … now see if you can … did that work for you … did you get my changes?” And pretty soon I’d figured out how to do the basic stuff: check out, update, commit. Part of the thing that demanded some trial and error on our part was that the source control menu text within Flare uses Microsoft Visual Source Safe terminology rather than the standard CVS/SVN terminology we’re used to (for example, “check out” means something different).

At one point in proceedings, as we were batting things back and forwards figuring out how it worked, I joked to Graham: “You know what we really should do? We’re technical writers - we really should be looking in the help system!”

Like most people (and I quite often bore people by asking them if/when/how they consult the documentation for the software they use, so I’m pretty sure I’m part of a majority in this respect) I only consult the help system:

• If there’s no local expert around to ask
• If I’m in a situation where I don’t want to ask the local expert because I don’t want to let on I don’t know whatever it is that I don’t know
• If I can’t find the information via Google, or I happen to know the help system will do the business for me (for example, I know I can easily find details of FrameMaker keyboard shortcuts in the application’s online help, but, in contrast, I know there’s little point looking in the online help for Microsoft Word because the search facility brings back so many inappropriate results it’s far quicker just Googling for the information)

And what about printed documentation? (It’s funny, when I talk about “documentation” a lot of people still immediately think of printed books, when in fact the work we produce only rarely ends up being printed. This is probably one of the reasons some folks prefer to talk about “user assistance” – but I find that term confuses most non-IT-professionals.) Well, let’s think … when do I read the paper manual for a software application … emm … never? Since I got broadband access to the internet (back in 2003 I think), I can’t remember ever having consulted a paper manual as a way of finding out how to do something in a software application. And I used to spend a small fortune on computer books. Before my access to the internet was “always on” my home office was cluttered with stacks of computer books and binders full of printouts. In the last few years all of that stuff sat untouched, gathering dust, and it was only towards the end of last year that I finally got round to chucking it out.

But back to Sue Wooley’s article:

Documentation is, therefore, rapidly becoming a backup for deficiencies in the user interface and user training rather than a complete solution in itself.

If you document software applications then you’ve almost certainly had the experience of having to document something when you know you’re writing a whole screed of instructions to compensate for a poor piece of user interface – and it’s obvious that simply moving things around the interface would make this bit of documentation redundant. That’s when documentation can be a bit soul-destroying. You of course petition the developers, log a bug or submit a change request, but in the meantime you have to document what’s there, in the full knowledge that you shouldn’t have to be writing this and the best outcome (for the end user) would result in the deletion of your work.

However, we have to be pragmatic about such things. Sometimes user interface design is just left up to some poor developer who, while he/she may be fantastically clever and a brilliant coder, has no real understanding of usability. And once a bit of poor user interface design slips out into a release it can be very difficult to repair because, unless they’re backed up by complaints from customers, requests for changes to the user interface generally get assigned a low priority. This can be very frustrating, if you’re the one who raised the issue, because some of these things can cause a lot of damage to usability but could be fixed by a little, two-minute change in Visual Studio. The hidden reality, though, is that even a quick two-minute change in Visual Studio can sap QA time by requiring changes to test scripts, updates to automated tests, manual regression testing, and so on. So a two-minute user interface change, that might prevent several hours of work by a technical writer, is often destined never to happen because of the QA cost and the feeling that any additional change carries a risk: so if it ain’t really broke, don’t fix it.

I don’t believe documentation should ever be thought of as “a complete solution in itself” (it should be an integral part of a product), but neither is it always “a backup for deficiencies in the user interface”. The products I work on are usually large, complex systems, where there’s simply too much in there to show it all on one page or in one window ­– with everything achievable within two or three clicks. Some of it just has to be tucked away somewhere to allow other things to be more accessible. As a result, you need some way of helping people find the rarely used pieces of functionality. Unfortunately you just can’t always make complex things simple within an application. Some things need explained. And as for training, well, you can develop and deliver a great training course, but what happens when someone completes a four-day course, covering lots of detail, but then doesn’t need to use a particular bit of the application until six months later?

There are good reasons why documentation is necessary. But, having said that, I’d still maintain that, in reality, for most of us, documentation is the form of assistance that you go to as a last resort, when there’s no other option.

But don’t get down-hearted. If you can create a help system that’s well targeted to provide people with the information they’re realistically going to be looking for, if you can structure it in such a way that people can find the information they need quickly without having to trawl through a list of 20 unordered search hits, if you can write concise and easy-to-read topics that explain just that nugget of information the reader needed to know … then your work is not in vain. Somewhere, some time, you’re going to help someone out. You’ll have avoided some aggravation. You’ll have reduced that day’s global curse count.

And sometimes, no matter how great the help system is, people will choose to ask a human being for help. Why? Well, because we’re social creatures and we’re often just looking for excuses for social interaction. Asking for help with the new IT system (or maybe just bitching about it generally for a while: I mean, the old system worked just fine – now I can’t get anything done!) is a chance to interact with someone, get to know the person at the next desk, chat to the girl in the next booth, make friends or maybe just kill some time.

And anyway, what’s so bad about providing a last resort? Isn’t it good to know we’ve provide people with something they can turn to when all else fails?