Writing ... or Just Practicing?

Random Disconnected Diatribes of a p&p Documentation Engineer

  • Writing ... or Just Practicing?

    Tragile Documentation

    • 0 Comments

    I just discovered last week that I'm supposed to be able to "move quickly and lightly", be "as sleek and agile as a gymnast", and be "fleet of foot". Either that or I'm supposed to be an X-ray and Gamma ray astronomical satellite belonging to the Italian Space Agency. Not much hope of any of these happening, I guess. Probably I shouldn't have decided to search the Web and see what "agile" actually means (and, in case you are wondering, the Italian satellite is called Astrorivelatore Gamma ad Immagini LEggero - see Carlo Gavazzi Space).

    All this comes about because one of the projects I'm on at the moment is effectively exploring the techniques for agile document creation. Agile is well-known in the software development arena, and it seems - from what I've seen here at p&p - to work well. OK, so it has its downsides from the documentation engineer's perspective (as I know only too well), but it does appear to produce great results very quickly, with fewer "issues" than the waterfall approach.

    So, can documentation be agile as well? A lot of the supposedly related stuff on the Web seems to be concerned mainly with creating dynamic content for Web sites, or creating content that you can display on different devices (such as mobile clients). However, there are a couple of people talking seriously about the issues. You'll find great articles from Scott Ambler (see Agile/Lean Documentation and Can Documentation Be Agile?) and Ron Jeffries (see Where's the Spec, the Big Picture, the Design?).

    Much of the focus appears to be on documentation in terms of the requirements of development teams (project documentation, such as requirements and design decisions) and operations (dependencies, system interactions, and troubleshooting). However, they do talk a bit about "customer" or "user" documentation. What's worrying is that all of the articles seem to recommend that writing user documentation should wait until the product stabilizes, be delayed as long as possible, and be written as close as possible to the product's release. Working on end-user documentation early in the project is, they suggest, just a waste of resources.

    Yet, if you don't start early and "run with" an agile dev team, how can you hope to have comprehensive user documentation available for the release? In theory, the team will capture all of the information required in models, sketches, and user stories that can be polished up to provide the user documentation. But is that enough? Should the whole design and structure of the documentation be based on developer's conversations and implementation specifications? Telling users that it "works like this" and "can do this" does not always produce useful guidance.

    For example, how many times have you opened up the help file for some complex server product and seen sections titled "Configuration", "Administration", and "Reference"? Maybe you want to do something simple, such as add a new account. You find the section in the administration topic called "Adding a new account" and it explains which buttons to click, which textboxes you need to fill in, and how to select an option for the "operations category". But it doesn't tell you why you need to do this stuff. Or what will happen if you do (or don't) select an operations category. What the heck is an "operations category" anyway? Maybe they are a fundamental new feature that got added to the product right at the end of the dev cycle, after the docs for creating a new account were completed. And so there wasn't time to do the fundamental reorganization of the content required to match the new conceptual approach you now need to take when creating an account?

    Agile development, they say, means that "working software is more important than comprehensive documentation". But all the articles and references seem to end up talking generally about documentation when what they really mean is "project documentation" - stuff for the team and project managers to use to monitor and manage the project. You continually get the impression that customer-focused documentation is neither a requirement, or important. Yet, without it, isn't there a chance that nobody will actually use the software? Or will never get the maximum benefit from it?

    Getting back to the question of whether you actually can do agile documentation for a software project, how might agile work? For a developer, a task might be something like rewriting an interception algorithm to improve performance, or changing part of the UI to make it easier to use. For a writer, a task is usually to produce a document that describes some feature. If that feature is sufficiently compartmentalized, such as describing how to use some part of the UI or explaining how to write some plug-in component, then it is an ideal candidate for agile. You can focus on just that task, and then move on to the next one.

    You can pair with another writer, or - even better - pair with the developer to help you understand the feature, and then use your "professional writer's abilities" (hopefully you have some) to get it down in a form that makes sense to users. And, because you don't have the same internal insight into the feature as the developer does, you can ask "user-level" questions and document the answers. Where it gets hard is when you are trying to grasp the "whole concept" view, especially from dev teams that know the code base inside out, instinctively understand the overall concepts of the product, and can't figure why, for example, anybody would find it hard to understand what an "operations category" is.

    I guess lots of people have carried out scientific investigations into all this, but my simple and humble take is:

    • Prioritization. If everything is gradual iterations towards the end goal, but the end goal is not clearly defined at the start, how do you plan the documentation requirements and prioritize the stages so you work on the right stuff at the right time? How do you know if what seems important today will no longer be important in a week's time, and might even disappear altogether in a month's time? To be effective when creating documentation, you need to be able to base it on an overall plan that has definable stages.
    • Concentration. Documentation development requires a similar approach, in terms of planning the architecture and linking the parts together, as code does. It also requires concentration, and is not a task that you can easily accomplish when paired, when time-limited, and when constantly shifting focus. Its fine for collating facts and information, but organizing and writing is still, I reckon, a "one-person" and "in a quiet room" task.
    • Flexibility. Trying to flit from one task to another is tough enough for developers, but it's often much more difficult for the documentation engineer where changes to the product are occurring all the time. There are no tools that allow you to automatically find and update references and content elsewhere in a documentation set.
    • Churn. While developers search for better ways to decouple their code components, in documentation you inevitably need close coupling. Topics can't link to some decoupled interface class - they have to link to a specific topic. Move, change, or delete the topic and it all breaks. Even a minor change to the functionality of a component in a large project can have a huge impact on the documentation. One way to tell a writer is to see if the labels have worn off the Page Up and Page Down keys on their keyboard.
    • Feedback. Inevitably the writer does not have the same level of insight into the product as the people who are writing the code, and in most cases doesn't have the same level of programming skill (if we did, would we be writers?). And, in most cases, not having the same insight is good because it means that the writer can act as the customer's advocate. But it does require constant feedback and input from the dev team, throughout the project if the documentation is being developed alongside the product.

    However, while these issues tend to arise when documenting a piece of physical software under development, the whole approach is different for the kind of task I'm currently engaged in. It involves producing guidance for technologies that are already released and are (generally) mainstream; for example, architectural guides and documentation that help you to use existing products. This is where you can actually work with something that is stable and finished (although they'll probably release an updated version just after you publish the guidance). Maybe agile works better here?

    What's interesting, and initially prompted this rant, is that I'm discovering how the traditional (i.e. not quite so agile) approach still seems to have some fundamental advantages. Documents I create from scratch to achieve a specific aim, working on my own in a quiet place, seem to come out better that those that get passed around from one person to another with everyone "adding their bit" but not seeing the whole picture. Being able to prioritize work myself means that I can spend time on the important tasks without being worried that there is some more urgent task waiting. And seeing the whole picture means I can write with more accuracy and less duplication of effort.

    I guess, in the end, I'm still struggling to see how you can use agile methods for end-user or consumer documentation. Maybe it needs to be some custom blend of techniques, concentrating on the features of agile and traditional methods that work best. Use the agile features of pairing for collating information, flexibility for maximizing effort, and feedback to keep it on target. Combine this with traditional approaches to prioritization, concentration, and an overall plan. Maybe it's a whole new paradigm? Can I trade-mark "tragile documentation"?

  • Writing ... or Just Practicing?

    Oending Letters

    • 0 Comments

    Oh dear, could it be that my brief career as a documentation engineer is about to come to an abrupt and unexpected end? Has my recent sin been so dreadful that I will be thoughtlessly cast aside, and once again reduced to wandering aimlessly around conference circuits and local dev shops with all my worldly goods in a shopping cart, trying to scratch a living by talking and writing about enterprise software architecture? Next time you see a sad and lonely figure dressed in a grubby (but geeky) T-shirt and scruffy jeans, clutching the tattered remains of a book on design patterns in one hand and a seriously out-of-date laptop in the other, spare a thought - it might be me.

    What was my dreadful sin? Well, in a recent article I used a rather too well-known abbreviation in the section that encouraged potential users to carefully study the documentation provided with the product before using it. And I nearly managed to sneak it past my editor, the policy checking people, and the entire legal team. But they caught up with me in the end. It seems, as a colleague explained, that they "have something against the letter F". Of course, I immediately took steps to ensure that we as a team never make that mistake again by sending them all an urgent email:

    IMPORTANT NOTICE TO ALL STA:
    Please be aware that, in uture we need to be ully aware o company policies and careully avoid any oending letters.

    Thankfully, and perhaps in part due to my prompt action, it looks like we've all escaped with just a slap on the wrist this time. OK, so I have to sit in the corner with a pointy hat on, and I'm not allowed any of those fancy p&p cheese sandwiches for a week, but it could have been worse. Especially if they'd known about my other recent word crime. And this was one that you can very easily commit.

    Imagine you're answering an email from someone asking about your new product. You reply in an encouraging "please buy it" way with something like: "The new Abracadabra Mark 2 is reliable, robust, and secure." No problem? Well, what if your customer buys one and it falls over the first week (reliable?), dies the second week when someone presses the wrong key (robust?), and finally suffers a successful attack from an intruder in week three (secure?). Yep, you should have said "designed to be reliable, robust, and secure", because - no matter how hard you try and how well you design it - nothing is ever going to be absolute. It's so easy to slip up when you're bashing out a quick email, but at least now you've been warned. Luckily my email never actually reached the "clicked Send" point...

    And, talking of email, if you'd been here last week by the server rack in my garage in the windswept and rainy (but strikingly beautiful) Derbyshire Dales, you'd have seen me jumping up and down like a cheer-leader, and whooping like a supporter at a presidential rally. Why? Well, stepping back a bit, it's all to do with "Unsolicited Commercial Email" (and isn't that a great acronym for junk email? I once wrote an article that was fairly iffy, but had the wonderful title "Spam Filtering - Is It Any UCE?").

    Anyway, I've been using the same personal email address for about 10 years, it's on every spam list out there, and so I get tons of junk email every day. I now use an outsourced email filtering service to control it, and they bounce something like 1200 spam messages per day (yes, per day) that are sent to random and non-existent names at my domain. Some spam does still get through, but not enough to be an issue. And with the money from all the lotteries I've won, the profit on my Nigerian Oil Company shares, and the commission for handling the legacy of the recently deceased King Alibongo, I'll soon be able to afford one of those brand new Rolex watches anyway.

    But the emails that really annoy me are those System Administrator messages informing you that "...your email offering Valium and male enhancement services could not be delivered to one or more recipients". Of course, when you examine the original message headers, it clearly didn't come from you at all - it came from somebody who spoofed your email address (assuming that your mail server is properly secured and you haven't been botted). Even more annoying, the Non-Delivery Report (NDR) says that "...delivery will be reattempted over the next three days." And it's absolutely pointless getting worked up and shouting "No, don't bother, just forget it!" at your mail server, because that's not where the message is coming from.

    So, a couple of years ago, I went to all the trouble of learning about Sender ID / Sender Policy Framework (SPF) in the hope that it would fix the woefully inadequate Simple Mail Transfer Protocol (SMTP) that we seem to be stuck with. I figured it out, created the appropriate text string for all my domains, and inserted the records into my DNS servers. And, to be perfectly honest, it seemed to do pretty much nothing - until last week when I opened an NDR from Google and found this:

    Delivery to the following recipient has been delayed: trin46yds@gmail.com

    And, there amongst the message headers, was:

    Received-SPF: fail (gmail.com: domain of a1ex@stonebroom.com does not designate 78.169.193.15 as permitted sender);

    Wow, they actually checked my SPF records and bounced the email because they knew it wasn't from me - it had a spoofed "From" address! At last all that effort was worthwhile. But further down the message it said: "...delivery will be reattempted over the next three days." And you thought I was the one who sent stupid email messages...

  • Writing ... or Just Practicing?

    A Phantom At The Opera

    • 0 Comments

    I suppose I could try to impress people by telling them how I spent a pleasurable evening at a concert at the Buxton Opera House a week or so ago. But as I don't have any posh friends, and only a few posh colleagues, I guess it's safe to admit that the trip was actually to renew an infatuation from my younger days. No, honestly, it's safe to read on. I promise not to descend into tales of a depraved, wanton, and wasted youth (though I wish I'd had one).

    The infatuee in this case is the fabulous Toyah - whose weird and wonderful style fascinated so many young men of my generation. Was it the mass of spiky orange hair? Was it the strange mechanical gyrations? Maybe it was the incredible wandering vocal style? Or just the fact that she was (and still is) gorgeous? And this revisitation to my adolescent infatuations was, in fact, my wife's fault. She saw that Toyah was guest-starring on the latest Vampires Rock tour, and graciously agreed to let me go and see her again after something like 30 years.

    So I was spared seeing opera, and instead saw an incredible show. If you get a chance (and you are into rock music), go and see this - or buy the DVD. It's the best night I've had for ages. The live band is superb, as is the scenery, lighting, effects, cast, and pretty much everything else. It's even got comedy, lots of (stage) blood and gore, and Emily Clark (who plays Pandora) has the most amazing voice. She does Suzi Quattro as good as Suzi Quattro, and "Total Eclipse of the Heart" very nearly as well as Bonnie Tyler. Just don't expect too much of a story...

    And, yes, Toyah was as wonderful as ever. Still as exciting to watch, and she still has a fabulous voice. It's just a shame she didn't get to do "It's a Mystery" or "Angels and Demons". Best of all, though, she is just as weird as she was thirty years ago. In fact she admitted in a recent TV interview that, after doing the Gobi desert "Great Walk to Beijing" with Danni Minogue, Danni had said that "Toyah was the maddest person she knew".

    But enough trivia. What continues to surprise me is how the technical management of shows like this is so bound up in computerized technology these days. When I was still at school, it was blatantly clear to all that I couldn't sing, act, remember lines, or look anything other than odd and geeky. So I never got a role in a school play. But I could build stuff like bubble machines and disco lighting gizmos (all driven by relays, cams, and zonking big washing machine motors in those days) so - together with some friends - we were in charge of the "effects" for plays and concerts.

    It took three of us to do thunder and lightning (with a tape recorder, dustbin lids, and a couple of spotlights), and five to untangle the microphone wires at the end of each act. And trying to get the right music and sound effects to occur at the right times was a massive feat of engineering involving 8-track cartridge players, BBC "Sounds Off" LPs, and large volumes of sheer luck.

    Now, it seems, they just press a button and the whole concert happens. I watched them testing some of the settings on the control deck. Or, rather, I watched one guy clicking the mouse a few times. The whole show, including sounds, lighting, effects, fireworks, and even the scripts and timings, are preset in some fancy Windows application. I guess it's just the natural progress of technology into all walks of life, but I wonder if it takes away some of the magic of theatre?

    Still, it will take something special to surpass the sight and sound of Luke Morley strutting across the front of the stage with blood running between his fangs while playing Slash's lead riff from "Sweet Child of Mine"...

  • Writing ... or Just Practicing?

    Help Upon Help?

    • 0 Comments

    I love how the Visual Studio Document Explorer (help viewer) has a topic named "Help on Help". I've often wondered whether it should say "Help Upon Help", like there was several layers piled up on top of each other. Or how, if you can't figure out how to use the Help file, a help topic within it would be useful. Still, I suppose it's better than the old days when you had help items such as "The Range property sets or returns the range" and "To close the window, click the Close button".

    But if your responsibilities include the creation of help sections for Document Explorer (as mine do on a regular basis), you'll know how fiddly it is to get the right stuff to appear in the right place, at the right time, and with a matching index. I suppose help-generation tools have never really been cutting edge, although there are some good third-party tools out there. And, of course, we have our own p&p Doc Tools to help us create the content. But it's the "massaging it all into a merge module" thing that has blood-boiling capabilities.

    Of course, you can create Help files using Visual Studio itself - if you can figure out the instructions in the help file, or even find the appropriate section. Here's a clue: you'll need to install the Visual Studio SDK and then find the topic Visual Studio SDK | Visual Studio Development Environment SDK | User Interfaces | Help Authoring and Integration | Help Authoring | Getting Started with Help Content and Integration. I guess that shows how important help authoring actually is...

    Anyway, as usual, I'm here to offer some useful nuggets of assistance (no laughing at the back please). Building a merge module for DocExplorer involves three stages: build the HxS and associated content files (TOC, index, etc.), use the VS Help Integration Wizard to compile these files into a merge module, and then test the merge module in DocExplorer by using a VS Setup project to install it. In our case, the p&p Doc Tools create the HxS and the other input files, though you can do this using other tools. Where I encountered problems was the conversion into a merge module.

    The issue is that, as the dev team builds stuff, they like to do regular CTP releases so that people can see where they are going and provide feedback (and, dare I venture to say, help them find the bugs). So our help docs get compiled into merge modules at regular stages. Each release has to have the correct headers, release dates, pre-release text, and internal namespace (each merge module is identified by a unique namespace). These details are specified in a combination of ways in both the input HxS files and in the VS merge module project.

    To build the merge module, you run the VS Help Integration Wizard. It collects all the information it needs to build a "plug-in node" (the root node of the set of help files in the Doc Explorer TOC), and then assembles all the files so that VS will merge the contents correctly into the existing sections of DocExplorer. The problem is that, despite spending many hours on many occasions searching, I can't find any way to re-run the Wizard when I want to change the settings.

    So, I thought, no problem. The input files are mainly XML so I can edit them. However, Windows is clever. I naively assumed that searching from Windows Explorer for files containing the text I wanted (such as the release date) would locate all the files I needed to edit. What I forgot was that the search feature only searches the contents of file types it knows about. Give it a mass of files with extensions like HxF and HxK and it simply turns its nose up in a kind of "you don't really expect me to look inside there, do you?" way. So I never could figure which files I needed to edit.

    But then, with the latest project, I decided I was going to solve the problem and used a "proper" search tool (actually TextPad, but don't tell anybody). Bingo! (or "Eureka" if you are posh). After some experimentation I'd found all the places that you need to change stuff. After that, I recompiled the merge module, recompiled the setup project, installed the merge module into Doc Explorer, and it worked. No need to nuke the merge module and setup projects and start over each time. Here's some pointers that might help:

     

    • To change the text of the "plug-in node" that appears in the list of installed technologies in DocExplorer, edit the PluginTitle attribute of the HelpTOC element in the _TOC_xxx.HxT file in the CollectionFiles subfolder of the project (the full name of the file includes some kind of project-specific GUID).

       

    • To change the title of the document set, edit the Title attribute of the HelpCollection element in the _Collection_xxx.HxC file in the CollectionFiles subfolder of the project.

       

    • To change the namespace for the document set, edit the content of the Namespace element in the IntegrationWizard.xml file in the CollectionFiles subfolder of the project.

       

    • To change the description of the document set, edit the content of the Description element in the IntegrationWizard.xml file in the CollectionFiles subfolder of the project.

       

    • The Filters element at the bottom of the IntegrationWizard.xml file specifies the filters you define in the Integration Wizard. These allow users to filter all of the DocExplorer content using the drop-down list of installed products and technologies. All of the pages in the HxS should have a DocSet specified in the form:
      <MSHelp:Attr Name="DocSet" Value="MyCTP1Docs" />
      If you changed the DocSet name, edit the Query child element of the Filter element to specify this, for example:
      <Query>"DocSet"="MyCTP1Docs"</Query>
      To change the description for this filter, edit the content of the Description child element of the Filter element.

       

    • To open your help file from a shortcut or code in an application, you use the rather convoluted shortcut path such as this:
      "%CommonProgramFiles%\Microsoft Shared\Help 9\dexplore.exe" /helpcol ms-help://MS.VSCC.v90/MS.VSIPCC.v90/[your-docset-namespace] /LaunchFKeywordTopic [keyword-in-target-page] /filter "your-filter-description"
      • The [your-docset-namespace] value is the one you specified in the Namespace element in the IntegrationWizard.xml file.
      • The [keyword-in-target-page] value is the value of the Term attribute of an MSHelp:Keyword "F" keyword element in the source page that you want to display, such as:
        <MSHelp:Keyword Index="F" Term="mycompany.myproject.yearmonth.introduction" />
      • The "your-filter-description" value is the value you used in the Description child element of the Filter element in the IntegrationWizard.xml file.

     

    As a side note, when you do test installs of merge modules, I'd sincerely recommend using a VPC with Visual Studio installed, but not much else. The merge process happens automatically when you open DocExplorer after installing a new merge module, and it can take ages if you have lots of other merge modules (lots of help topics from lots of other installed products). Using a VPC means you can test the installation, then abandon (delete) the changes to the VPC so you don't have to uninstall the merge module again.

    If you don't use a VPC, remember to open DocExplorer and then close it again before you install the merge module to ensure that there are no other merge changes pending. And after you uninstall a merge module, make sure you open DocExplorer again to let it sort itself out - it remerges all the remaining content again. If you uninstall and then reinstall a merge module without allowing it to remerge, you may well see the old module content instead of the new content unless you changed the namespace in between.

    Or just give users the original Word documents and let them print out their own help file...

  • Writing ... or Just Practicing?

    Convoluted, Devoluted, Or Just Engblish?

    • 0 Comments

    Maybe I've been asleep for the last few months, or just head-down working on my current project, but it seems I am the only person in the world who wasn't aware that a new version of Windows was on the way. Well, the only geek anyway. I don't mean the "Mojave" stunt - I mean what is currently referred to only as "Windows 7". And, rather strangely, my first thought when I read about it in a UK computer magazine was "Wow! Has there only been two and nine-tenths other versions since the Windows 3.1 that we all knew and loved?" That introduction to millions of the Windows world of GUI seems so long ago now...

    Other stuff that followed closely in terms of mind-springing was probably even less the kind of thing that the marketing department would hope for. I couldn't help seeing misty visions from the past of the Austin 7 and, of course, Blake's 7. But no doubt there is already a selection of swish names being brain-stormed in the palatial offices of the "Let's get out there and sell it!" brigade. Seeing as everything these days is "Web 2.0" and "Community-driven", maybe they'll hold a competition and let the winner choose a name. I'd be no good at that. I could never figure why they called Vista "Vista" (if you see what I mean). I thought it meant "Goodbye until we meet again", as in the film Terminator, until I discovered that the "Vista" bit means "seeing". I guess that makes sense because my Vista laptop is the first one I've ever had with a built-in camera (even if there aren't any Vista drivers available than can make it work).

    So, anyway, this computer magazine asked users what they wanted to see in Windows 7, and one of the top answers was support for the local culture and language. Yes, they mean "proper" English with all the missing letters reinstated or changed round into the correct order. They want a "Favourites" menu and a "Security Centre". And maybe even the Queen's English as well - how about: "One is asked to wait patiently during the processing of the current request...". I suppose that would mean they'd need to make all the dialogs bigger, but it would be rather nice to have a polite computer. "Excuse me, but it does seem as though there is a recently-arrived email message awaiting one's prompt attention."

    Of course, it wouldn't stop there. I mean, doesn't anybody else realize that there is no such country as "UK"? England is a country, as is Wales, Scotland (and, I guess, is Northern Ireland). Yes, there used to be a "United Kingdom" (about 300 years ago), but now that the Scots have got themselves devoluted, and the Welsh are part-way there, it's hard to see how we are still "United". I, as thousands of other people do, refer to my country by its real name - even to the extent of chancing my luck at U.S. Immigration by putting "England" on my visa waiver form!

    Wandering off topic, it seems that Wales is actually a new standard measure of area. When you want to amaze people with how big something is, such as the size of an Australian sheep ranch or the area covered by Lake Superior, you quote it as multiples of the size of Wales. As in "Did you know that Lake Superior is four times the size of Wales?" Don't believe me? See sizeofwales.co.uk.

    The other option, which I can live with, is "Great Britain". I like the sound of the "Great" bit, even if we aren't really that important in world terms these days, and it's handy for doing TV programs and stuff like a list of the "Great Britons" of history. And, of course, we do have our own language/culture code "en-gb" which just goes to reinforce this (so, Windows dev guys, you ain't got an excuse for missing us out). Maybe to save confusion they could incorporate the culture code and call it "Engblish" instead?

    And if "gb" is the accepted term for Great Britain, when are all the Web sites in the world going to fix their address entry list boxes? If they can't be bothered listing all the countries, we should at least be "Great Britain" instead of "UK". I mean, they list other countries using the proper name, or at least a translation of it. The culture code for Spain is "es" for "España". And I'm sure that China isn't called "China" in Chinese (why would it have the culture code "zh" if it was?). OK, so I could look it up, but I probably don't have the right keys on my machine to type it here anyway. Oh, and while we're talking about China, did anyone realize that the number 7 in China is supposedly related to anger and abandonment...? (see Travel China Guide.com).

    Still, I suppose the "name of my bit of the world" thing happens on a smaller scale as well. Here in Engbland, many years ago, they decided to steal lumps of East Yorkshire and Lincolnshire and rename them North Humberside and South Humberside. The rumour at the time was that the Government needed to justify building a bridge that cost hundreds of millions and went from a major coastal city to nowhere in particular (or maybe the posh folk in the East Riding of Yorkshire just wanted rid of Kingston-upon-Hull). Of course, nobody took any notice and kept writing their address as "Yorkshire" or "Lincolnshire". After a while, South Humberside got renamed again to "North Lincolnshire". I wonder how much money all that wasted?

    And now, horror upon horror, they want to move Lowestoft from Suffolk into Norfolk. I assume they mean moving the county boundaries, not actually packing the town in boxes and loading it onto a big truck. Question is, will the genteel people of Norfolk be able to cope with a town so famous for being the place that created "The Darkness"..? Come back Justin, we want more.

  • Writing ... or Just Practicing?

    Build It, And They Will Blame You

    • 0 Comments

    Here in England, architects (the kind who design houses and office blocks) seem to have a pretty poor reputation. Other than the "stars" who win prizes for designing skyscrapers, or weird shopping centers that look like an armadillo that wandered into a chrome-plating factory, they seem to be universally reviled. Perhaps it’s the same in the US. I remember once hearing the quip "Don't tell my mother I'm an architect, she thinks I play piano in a whorehouse". That sounds like a US-ism if you ask me.

    We have a TV show named "Grand Designs" where people with huge ideas and equally huge piles of spare cash build strange houses. While all the houses are very different, all the shows have some things in common: it always costs more than they budget, it always takes longer than they planned, and they always fall out with the architect. Somehow you just know that the cantilevered roof won't pass building inspection, the windows won't fit, the kitchen will be totally impractical, and the rain and snow will ruin the exposed timber beams before the roof tiles arrive (though maybe you can't actually blame the architect for that).

    The only show I can recall where it all went right was a young couple who bought an old pumping station for about £5 ($10), made a fortune selling the pipes and tanks for scrap, did all the work themselves over a two year period, and turned it into the most fabulous place with a lounge area so big they used a cut-down Mini car as a desk - and you didn't notice it till they pointed it out. Strangely, the house is only a few miles away from me, but when they sold it, the price was the equivalent of a million dollars US. Somewhat out of my reach unfortunately. Shame, I could probably have parked my car in the bathroom to wash it.

    So, anyway, I wonder if software architects face the same problem. Do developers stand back from some complex business layer component and mutter "We'll have to chop some lines of code off that if you want it to fit into the server...", or "That data access layer will fall over the first time we get a decent breath of wind blowing off the hills...". Maybe the administrator goes off in a huff mumbling "Typical architect, never specified a long enough piece of HTTP to connect the Web server to the database server...". And the project manager is left to give you the bad news that the event handlers the architect specified are only available from one factory in Sweden, and they are closed for the holidays.

    As an aside, it's actually illegal in the UK, according to section 20(1) of the Architects Act of 1997, to use the term "architect" in your job title if you don't have "appropriate" qualifications (see Regulation of Title). Though the Architect's Regulation Board seems a bit more relaxed about it these days. But I did hear that at one time they were trying to enforce this and make software people use something like "Software Designer" instead. What they probably meant was "Jumped up geek who does stuff with computers..."

    Of course, in building houses terms, the architect is probably long gone when it all goes wrong, or is protected by something in the vast wad of small print. But I suppose you have to feel sorry for them. I mean, in terms of software projects, I never heard yet of one where the delays, bugs, lack of performance, or cost over-run were blamed on the architect. It always seems to be the developers fault. So guys, here's your answer. Lean back in your chair, suck your teeth and make that "not-my-fault" whistling sound. Then explain to the project manager that it's all the architect's fault. He designed it, you only built it...

    And maybe add that you couldn't get the right bits...

  • Writing ... or Just Practicing?

    Gone Shopping...

    • 0 Comments

    (OK, need a good, hard-hitting, gritty opening sentence this week to get people interested. Here we go...). Last week I went shopping. (Hmmm... not quite the impact I wanted, but press on regardless). I wanted a new battery for my camera, so I popped into a local specialist. "Hi," I said breezily, "I need a battery for an Olympus 1010 Stylus camera". "OK," replied the obviously knowledgeable young man behind the counter, "just fill in this form". He presented me with a long form where I had to enter my name, address, credit card details, and a myriad other details. Finally, when I gave it back to him, he said "Right. We don't actually have one in stock just now, but it should be here in a couple of weeks". Needless to say, I tore up the form and stormed out in disgust.

    Across the road, I noticed a rather interesting looking computer store, and decided to have a wander round. After about half an hour, I'd filled my shopping basket with a dozen or so items, and sauntered over to the checkout. Suddenly, a rather aggressive looking lady took my basket off me and disappeared. After a few minutes she returned and gave me back an empty basket, explaining that there was a problem with the cash register, but I was welcome to go round the store again and refill the basket. I decided not to bother.

    Somewhat irritated with the day's events, I thought I'd calm my temper with a cup of coffee and half an hour with my newspaper. A few doors down the street I found a nice coffee shop, though I was more than a little perturbed to see a sign on the door that read "Warning: for your safety you should only enter these premises wearing a red satin waistcoat and brown leather shoes". Now, red doesn't go with my complexion, and I don't own any brown shoes, but I decided it was worth the risk. However, I did ask the pleasant young lady behind the counter if I could see the manager to complain about this blatant discrimination. She replied that I had to tell her the password before I could speak to her boss. "How can I find out what the password is?" I asked. "I don't know", she replied, "He always keeps it in a sealed envelope in his pocket".

    Deciding that drinking coffee here was perhaps beyond my risk threshold, I left and strolled across to a large branch of a national well-known supermarket chain. There I had a nice cup of coffee in their restaurant, wandered round and collected all the stuff I needed, was greeted by a helpful and efficient checkout operative, and was on my way home in no time.

    Of course, you will probably have guessed (if you are brave enough to have stuck with it this far) that the preceding is all a huge fabrication. Or, at least, it's partly a fabrication - and may just serve to indicate how stupid things can get in our modern, high-tech, shop-on-line society. In fact, last week I did...

    • ...try to buy a camera battery from a specialist online store where I had to register before I could go to the checkout, but they didn't tell me they had no stock until I placed the order.
    • ...spend half an hour on an office equipment Web site finding all the odd bits I needed, then was faced with an error message at the checkout and an empty basket.
    • ...visit a blog site that told me I was using an insecure browser (Internet Explorer), and that I should be using Firefox or Opera. And when I tried to submit a comment, discovered that I had to read and type the letters in some weird image with no alternative option for visually-impaired users.
    • ...end up on Amazon.co.uk, where I got all the stuff I needed. And they delivered it two days later.

    It does seem strange that, after more than ten years, we still seem to be struggling to provide an Internet that works reliably, works in all browsers for all users, and actually makes life easier. People even seem to spend more time worrying about how that CSS border line is "two pixels off", and that some browsers don't "fully support all the standards". It's not hard to see why the big boys in this game continue to grow, while so many others fall by the wayside. OK, so it is hard to get right, especially for small sites with limited resources. Perhaps the answer does lie "in the cloud" with "Software plus Services" (S+S).

    So would you trust some outside organization to provide all the services your business (or hobby Web site) needs? In my previous life as a creator of retail software and purveyor of IT services, I always said that I would provide my own infrastructure and services to make sure it did what I wanted, was always available, was secure, and was under my control. I run my own Exchange Server, public DNS, and Web sites. Yet, looking at my systems, I was surprised to see how much I already outsource. Before becoming a 'Softie, I used Powernet to filter my incoming email. I used LunarPages to host large file downloads and one of my Web sites. I used DigitalRiver to take orders and process payments for my software products. And this blog is hosted on MSDN. One of my colleagues even uses an online source code repository and an online backup facility.

    I guess when you think about it, it's hard to see why anyone would start now to create a new general-purpose search engine site to compete with the few guys who already own the market. Why would anyone want to build a new auction site, when it's so easy to use EBay and the like? And small retailers seem to be congregating in their thousands around the in-store shopping services available from Amazon and others. Maybe the future is a relatively small number of "in-cloud" service suppliers, with the majority of sites hosted there.

    But why "cloud"? In his blog post "Can We Please Define Cloud Computing?" (which presents some interesting views of the topic) Mark Hopkins mentions that the first time he saw the use of of the cloud symbol was in diagrams of MCI's ATM router mechanism. I remember way back when we were writing our first Internet books (about Internet Explorer 3) at Wrox Press we decided to use a cloud symbol to represent the Internet in our schematics - it seemed the obvious choice and represented stuff that was "going somewhere else, but not sure how". Isn't it amazing how a whole technology can get its name from a PowerPoint shape...

  • Writing ... or Just Practicing?

    Profligate Profiles

    • 0 Comments

    At last I can document something that might, possibly, be of marginal use to those one or two readers who mistakenly stray into the quagmire of my unrelated weekly ramblings. For the last few months I've been fulfilling my new role as an out-of-sight-and-out-of-mind remote documentation engineer (that's a documentation engineer who's remote, not an engineer who writes remote documentation - though, having read some of my scribblings, you might dispute that assertion). Anyway, recently I was beamed up to the mother-ship to spend a couple of weeks onsite at Redmond. I suspect they just wanted to see if the weird English guy they accidently offered a job to actually does exist.

    So a while ago, while preparing my shiny and tiny XPS laptop for the trip, I had a minor moan about Vista's backup facility. But little did I realize that worse was coming my way. My laptop usually lives on the corporate domain, even though I only connect to the domain over a VPN and am not connected during login to the machine. The cached domain credentials allow me to log into the machine without being connected, and then the O/S authenticates me on the domain when I connect to the network.

    All fine so far. Except that, for some reason, one day it suddenly stopped me from logging in to the machine. I assumed that this was because I hadn't physically connected to the domain for several weeks. So it should all sort itself out when I can reduce the 5,000 mile gap between my laptop and the nearest corporate Ethernet socket. The domain controller would be forced to accept that I'm not just some ethereal figment of its Active Directory, and would gleefully welcome home it's long-lost prodigal son.

    Now, I'm not generally known to suffer from wild spasms of optimism. And so I wasn't really surprised when the long-awaited fusing of my tiny little Dell with the corporate big-iron simply resulted in an Event Viewer full of error messages, a pop-up telling me there was an error in my profile, and the machine refusing to persist any changes to the environment. Every logon was accompanied by a long wait while Vista "prepared my desktop" (I could have built a whole desk in the time it takes), a task bar full of useless notification icons (what the **** do they all do?), dialogs welcoming me to the exciting world of Windows Vista (yes please, I'd love to watch the introduction video again), the Home page of Dell Support's Web site (just in case something broke while booting up?), and - of course - none of the useful stuff I set up last time.

    After a quick consultation with the onsite server admin guy (hi Mike), it seemed like this is not an unknown issue - he had a laptop suffering from just this malady. While he hadn't had time to investigate, he did confirm that it was a problem with Vista not being able to create the profile folder on the local disk. But why? The relevant folder did not exist, the parent folder was not read-only, and a quick test by manually creating the required folder had no effect. So it looked like I was in for another of my regular hunt-round-the-Registry-and-delete-stuff exercises.

    Of course, as per accepted administrative guidelines, I need to warn you about editing the Registry. So, before you start, make sure you write out your will, lay in supplies of pizza and cola, and say goodbye to the kids and the dog. You might also like to wear some protective clothing (a T-shirt with a suitably inane slogan will do), and make sure there is nothing valuable in the direction you are likely to throw the unbootable machine afterwards.

    Once prepared, locate the Registry Key:
    HKEY_LOCAL_MACHINE
     \SOFTWARE
      \Microsoft
       \Windows NT
        \CurrentVersion
         \ProfileList
    This contains a subkey named with a SID for each user account on the machine. In theory, there is one for each of the named folders in the C:\Users folder on your disk. If you select a SID subkey, you'll see the user name in its subkeys, so you can compare each one with the disk folders. You should find ones for the Administrator, Local System, and Network accounts; as well as ones for all the users registered on the machine or in the domains you've joined.

    My machine has led a busy existence during its short life, moving between three domains and having a couple of local users. During a "routine clean up", I seem to remember deleting some of the subfolders in the Users folder - though I was, of course, careful not to delete any currently registered users. What I discovered was the Registry still held references to profile folders for accounts that no longer exist on the machine, but not one for the domain account I was trying to use. I have no idea why this caused a problem, but I decided to tidy up the Registry while I was in there and deleted the SID subkeys, including all their child subkeys, for all of the non-existent user accounts.

    Then, having decided which wall would be the target for an airborne laptop, I rebooted. And, magically, it all worked. Instant logon to the domain, wireless certificates downloaded and installed, and no errors. Quick reconfigure of the desktop, log off, log on again, and it remembered my settings. No more "Welcome to Vista" stuff; and everything working just as it should. Even Outlook managed to find its Exchange Server without the usual application of a large stick. Amazing. Maybe I can actually get to love Vista after all...

Page 39 of 41 (325 items) «3738394041