Writing ... or Just Practicing?

Random Disconnected Diatribes of a p&p Documentation Engineer

  • Writing ... or Just Practicing?

    Is it a Scenario? Is it a Case Study? No, it's an Opportunity


    A few influential people in our little world of Developer Guidance here are Microsoft have recently been avoiding the word "scenario". It seems that it's now so overused, and has so many apocryphal meanings, as to render it useless in terms of determining user's documentation requirements and for planning the creation of product guidance.

    As my job description includes "creating scenario-focused guidance" and "exploring typical customer scenarios" this could be a bit of a problem (maybe I've become overused and apocryphal as well). Perhaps, in line with the current trend to make guidance simpler and less formal by using common words and "talking to the user", we should replace "scenario" with "needs" so that I can just "explore typical customer needs".

    However, my US-English thesaurus doesn't list "needs" as an equivalent to "scenario", but it does list "situation", "state", "set-up", "picture", and "development" - none of which feel quite right. If I created "state-focused guidance" people will probably ask if it applied only to developers in Wisconsin, and "set-up focused guidance" wouldn't seem to be much use after you'd finished installing the application.

    But where we had a struggle this week as we continue to develop the structure and plan for our upcoming guide on Big Data and HDInsight is with the difference between "scenario" and "case-study". We want to create some examples of using HDInsight that correspond to typical users' requirements, covering different types of data and query approach. For example, as well as the old chestnut of analyzing web log files, we want to do something with numerical data and social media content.

    We have an outline of the examples, but I still need to decide how to present them. If I phrase each one as though it had been done by some fictitious corporation (yes, you guessed: Contoso) and show how they did it, it seems like it will be a "case study" that is specific to that organizations needs. But can it really be a case study if the organization doesn't actually exist?

    If I phrase it as a step-by-step explanation of how you would do it yourself then it seems like it's an "example". And the code that we provide for download will be a "sample". The "scenario", meanwhile, looks rather like the umbrella under which all of this occurs. Maybe I'm just a parenthesis short of a lambda expression, but to me it appears as though there's a hierarchy of things here - something like:

    Scenario -> Case Study -> Example -> Sample

    where a scenario describes the requirements and a case study provides the solution by including an example of how the sample code was used.

    The problem is that many people seem to be put off by case studies because the natural initial response is that it will be specific to somebody else's requirements rather than their own. But while this may be true of case studies that show real life implementations, such as how [insert name of global company here] saved 30% on pizza and cola by adopting Hyper-V, we're inventing a case study to resolve a scenario that we also made up.

    However, we made up the scenario based on feedback from real users and advisory boards, so it must apply to a lot of people. Therefore the solution should also be relevant, especially where we explore different options and show alternative implementations - together with, of course, guidance on which to choose based on your own specific needs. So it can't be a case study because now we're covering several cases.

    I was going to say "catering for several cases" there, but I was worried it would just make readers think about pizza and cola again.

    So do we need a new word to replace the possibly deprecated "scenario", and what should it be? Obviously it's not "case study", and "example" just sounds too minimal. We could try falling back on the old technique of combining words, though "scexample" sounds a little dubious. Mind you, it could be worse. Once the marketing people get started on this we'll end up with some action-based, solution-oriented, brainstorm-generated word to replace "scenarios".

    I'll probably have to call them "opportunities" instead...

  • Writing ... or Just Practicing?

    Just Press F1!


    I'm increasingly seeing how big the disconnect is between people who use computers occasionally just because they need to do stuff on the Internet, and those of us who live and breathe computing. And we're not talking stupid people here; I see it most weeks with friends and acquaintances that are fully capable of managing almost any other technological domestic device.

    It's both interesting and worrying. Interesting because I'm part of a group within Microsoft working on a project that will help to discover more quickly and more accurately the issues people typically face when using our products. While here in p&p we are tilted towards the needs of developers, software designers, and system admins, I'm interested to learn how you can make operating systems and user-oriented software easier for home users to grasp. After all, we spend inordinate amounts of time and effort making them intuitive, and providing pop-up help pages and tips.

    And it's worrying because, for most of the non-technical population, having to spend time learning how to use technology is a thing of the past. We want instant gratification. Few technological devices come with proper manuals these days anyway (it's all on a CD that gets lost within minutes of opening the box), and instead these devices have intuitive UIs that mean you don't need to resort to the help file. Although I have to admit that some do seem to make common tasks difficult - our new kitchen oven has so many knobs and buttons, and different cooking settings, that my wife keeps the instruction book handy just to decipher the strange symbols.

    Coming back to computers, though, this week I encountered a perfect illustration of the issue. Some friends called round, complete with laptop and a list of questions, seeking my help. They could no longer print anything because the Print button and menu bar had disappeared from their web browser. Plus, the desktop shortcut that opened their email now just showed Google search engine. And they were concerned that they'd lose all of their precious photos if the computer broke down or was lost because the backup software couldn't find them.

    It took only a cursory examination to discover that Internet Explorer seemed to have disappeared, and now all their web shortcuts had a Chrome icon - which I assumed was down to the recent Adobe Flash upgrade (see Not So Shiny). Rather than uninstalling Chrome I just fired up Internet Explorer and used the Programs tab in the Internet Options dialog to make IE the default browser again. This meant that they now had a Print button on the toolbar, though I still had to mess about resetting the Home page and the link to Hotmail.

    But they still couldn't figure out how to get the menu bar to appear in the browser. They never realized that you could click the little down arrow next to the Print button to see more printing options, and always did that before using the File option on the menu bar. I explained that they just had to press the Alt key to see the menu bar; but, other than mumbling something about extra room for the content of the page, I couldn't answer the subsequent question "Why?" So I reset the menu bar to be there all the time. Yet all of these operations are explained in the help file - if only I could persuade them to press the F1 key!

    And then we got to the question of backing up their photos. Some while ago I'd given them an old USB thumb drive and copied their photos onto it. But now, every time you plug it in, the computer just displays a dialog saying "No more pictures found to import". It turns out that, when they bought a new printer a while ago, another friend had installed it - along with all of the accessory programs that came with it.

    One of these programs was a utility that scanned for photos and displayed them for printing, and this program had helpfully set the autoplay option for USB thumb drives to run itself. Obviously it had imported all the photos from the thumb drive the first time it ran, and so there were no new ones. They thought the program was saving the photos onto the thumb drive, but examining it revealed that it contained only those I'd copied to it a year ago. None of their later photos from several trips abroad had been backed up.

    To sort this out I had to go into the Autoplay settings in Control Panel to set it back to "Ask me every time", and then create a simple batch file in the root of the drive to copy the new photos. But, of course, there wasn't room on the thumb drive for all the new photos so we fetched a 500GB USB disk from a local store and I set up the batch file on that. Now all they need to do is run the batch file after loading new photos, music, videos, or documents onto the computer and they'll all get backed up automatically.

    Except that, until you come to show someone how to do this, you don't realize how unintuitive it all is. Plug in the drive and wait for the autoplay dialog. Select "Open folder to view the files". Double-click on BackUpMyFiles (the name I gave to the BAT file), wait until the black window disappears, close the window showing the files on the USB drive, click the icon in the notification area that looks like a tall thin box with a tick on it, select "Disconnect storage drive D:", wait for the confirmation message, and finally unplug the drive. And if you forget to close the file window first you get an error that the device is still in use, but no indication of what to do about it.

    OK, so this is Windows Vista, and thankfully Windows 8 can do all this through the cloud much more easily. But, despite my pleas to upgrade, they're unlikely to do so any time soon (probably only when the computer breaks down and has to be replaced). And they are the exception - most home user help requests I get are still for Windows XP.

    Perhaps when I make my fortune and become a philanthropist my calling will be to upgrade everyone I know to Windows 8 for free, though whether it will install on my neighbor's ten year old HP tower computer (which doesn't even have a built-in CD drive) is questionable. And we'll probably be on Windows 23 by then anyway...

  • Writing ... or Just Practicing?

    UPS I Did It Again


    There's something rather disturbing about sitting on the sofa looking at a large brown water stain on the lounge ceiling while the mains electricity circuit breaker is occasionally tripping out. Somewhere in the back of your mind is the worrying thought that the two events might be connected. And that another stream of tradesmen, who will tear up the floor and bash holes in the ceiling, is imminent. And that's after three months of visits from men with toolboxes, and startlingly rapid deflation of my bank balance, during our recently completed house modernization saga.

    Before I ramble on any further, however, I guess I should apologize both for the overuse of bad song titles (see also UPS Outside Your Head), and the strange focus on boxes with a big battery inside. As you probably guessed by now, we're back in what's turning out to be "interruptible-power-supply" land. And something I've never seen happen before with a UPS.

    I've been using APC UPSs for more years that I like to remember, and generally they do what you expect. After a while, or when they get a bit too warm, the battery inside starts to expand and stops providing backup power, but for the rest of the time they just sit there - maybe flickering a few LEDs now and then, and beeping contentedly when the mains power goes off.

    There's four 1000W ones in the server cabinet in my garage powering all of the hi-tech stuff you need to connect a few servers to the Internet and an internal network. One of the servers is a cold-swap backup Hyper-V host that can take over all the VMs if (or, more likely, when) the main host server dies. I power up the backup server once a week so it can sync Active Directory (and to check that it still works, you know what computers are like). When it's off I usually turn off its UPS as well, though that's still connected to the mains supply so the battery is kept charged.

    But last week when I pressed the "1" button to turn it on (which automatically boots the server) it immediately tripped out the overload protector in the main fuse box for that ring main circuit. Could this be the cause of our mains electricity problem? But the server powered up fine running on battery so the inverter is obviously working, and the overload switch on the UPS was not tripped. Maybe it's a problem with the battery, though that seemed unlikely as it was powering the server, but I replaced it anyway and everything seemed to work again.

    At least it did for a while. After scurrying repeatedly (often in complete darkness) for the fuse box reset button at various intervals during the next two days, and several other experiments trying to isolate the fault (isn't it amazing how many things you have plugged in around the house when you are trying to figure which one is playing up), I decided it needed more decisive action.

    When I disconnected and removed the UPS from the cabinet it was quite warm, and an examination of the internal gubbins looking for stray wires or that familiar burning smell offered no clue. Could it just be the cold wet weather we've been having for a couple of weeks causing condensation inside? Yet we have cold wet weather every year (often it's the default climate setting here in England), so why should it suddenly happen this year?

    However, after a day next to a radiator in a warm kitchen, I test the UPS and it's working fine again. It looks like it didn't take well to having a hurricane of freezing cold and damp air blown over it for a week while the server was powered down and not drawing any current. Though it did start tripping the circuit breaker again a few days later after I reinstalled it, even though I left it turned on this time. But I suppose it makes a welcome change to the more usual situation of trying to keep everything in the server cabinet from melting during the rest of the year. Maybe it's time to invest in temperature-controlled fans?

    And the large brown water stain on the lounge ceiling? I do seem to remember having a bathing accident a while ago, at the time when the bath panel had been removed to lay the bathroom floor, so I'm fervently hoping that was the cause...

    Footnote: After the UPS tripped the circuit breaker again I gave up and replaced it (there are good deals on reconditioned ones around at the moment). Perhaps I'll give this one another try in the summer to see if it's got over it's bad habit.

  • Writing ... or Just Practicing?

    In Search of the Mysterious Yellow Wire


    Thankfully I don't get many desperate requests for computer-related assistance from friends and acquaintances. Maybe they're frightened I'll ask for money (I won't), or they just don't want to bother me. And those I do get are usually the common issues that - other than the requisite amount of "fiddle time" - don't take much to fix. But this week I actually beat my previous record of fast fixing by solving a problem that just needed me to press Fn-F10.

    Some friends had phoned to say that their ADSL connection wasn't working. They'd talked several times to their Internet provider on an expensive premium phone line, but it didn't seem to help. The router kept dropping out, it seems, though after a day the magic green light was back on. However, now their computer could not find any wireless connections.

    The solution that their ADSL provider suggested was to "plug in the yellow wire". They had no idea which wire was meant, and so the support guy told them they would have to go out and buy one. And if that didn't work they'd need to replace their computer as it was obviously broken.

    So my friends then phoned me because they were concerned that going into a computer store and asking for "a yellow wire" might give the impression that they didn't really know what they were talking about, and they might end up with the wrong thing. I guessed that what they needed was a CAT-5 Ethernet cable, and confused them completely by saying I had a spare "yellow wire" that was blue, and that they could have for free.

    However, I suspected that the real problem with the wireless was that it was disabled in the Manage Network Connections dialog, turned off by the hardware switch, or the wireless card had failed. After I got them to search in vain for a switch on the outside of the computer (it doesn't have one) I toddled off to their house with my laptop (and the blue yellow wire) to investigate further. And, as you may have guessed, the problem was that the wireless connection on their computer was simply turned off.

    Turns out that the support guy had told them to press "weird combinations of keys", which I assume included Fn-F10, to ensure that wireless was turned on. This made no difference at the time because the router had lost its connection, and all they'd achieved was to toggle it off. By the time I got there the line problems that were causing the router to drop out had obviously cleared because I could connect to it without any problem. And so fixing their computer just needed a quick prod on Fn-F10.

    Ah, if only all the problems I tackle were as quick and easy to fix. Of course, after the computer was working OK again came the "extra" questions: "Can you make the browser open my email", "Where have all the photos I had on my camera gone", and of course "Can you make it run a bit faster"...


Page 1 of 1 (4 items)