Writing ... or Just Practicing?

Random Disconnected Diatribes of a p&p Documentation Engineer

  • Writing ... or Just Practicing?

    Defensive Writing


    One of the facts of life when you write technical documentation and guidance is that it will get reviewed by other people, resulting in regular changes to the content as you try to follow shifting advice, conflicting feedback, and suggestions that sometimes even make sense. It doesn't help, of course, if the technology you are documenting is also a moving target.

    I don't profess to be an expert in all the technologies we cover, but I generally have a good grasp of the fundamentals for each one - such as what it's supposed to do, how it does, it, and how you can use it. But I depend on reviewers and feedback to make sure I covered all the relevant points, and that what I've written is accurate as well as being useful.

    Over the years, I've come across many situations where it's useful to write defensively in order to minimize errors and illogical content, and to reduce the work required to get the stuff finished and out of the door. While they might not be applicable to everyone, here's a few things to think about:

    • Don't include a number in the introduction to a list. The number of items will change. A list of four items that starts "The following four types of data store..." will look silly after you add another one in response to reviewers' comments and forget to change it to "five".
    • Look out for overuse of your favorite words. I found I'd used "encompass" three times in one paragraph before I proof-read it. Use a thesaurus (even the Word built-in one) to find equivalent words and phrases.
    • Beware of including numerically accurate information such "costs x" or "is x times faster" because it will be wrong next week. Words such as "considerably", "minimal", and "cost-effective" are often just as useful.
    • "At the time of writing..." makes sense only to you. Put the date in.
    • Check out commonly accepted information before you accept it. For example, Hadoop was originally created at Yahoo!, not by Apache.
    • Beware of your "only" positioning:
      • "Only developers can use feature x to confirm the results" (nobody else can use feature x to do this)
      • "Developers can only use feature x to confirm the results" (developers can't modify feature x)
      • "Developers can use only feature x to confirm the results" (developers can't use any other feature to do this)
      • "Developers can use feature x only to confirm the results" (developers can't use feature x for any other purpose)
    • Leave all the comments in until you go to release. You'll get conflicting feedback from different reviewers and you need the history to figure out why you changed something in the document, and what actually is correct.
    • Get inside your reviewers' heads. Some will comment only on the bits that interest them, so you can't assume the rest is accurate. Others will offer half-thought-through or off-topic suggestions that are not directly relevant (but might be useful elsewhere). Look out for hobby horses and special interest comments that will bloat the content without adding anything useful. Lazy comments such as "You need to cover other stuff here as well" but don't say what you missed probably need to go back to the reviewer, but don't expect much additional help.
    • Beware of the cleverness of word processors such as Microsoft Word. Removing a comment can sometimes insert a space, which can be a problem in code listings. Deleting the word before a word that starts with punctuation (such as ".NET") removes the space before the word. For example, deleting "Microsoft" from "the Microsoft .NET framework" results in "the.NET framework".
    • Minimize deep linking by linking to the home page of another site where possible, and tell the reader where to look, as long as it does not make the reference unusable. For example, "See the documentation for feature x on the [link]targetsite.com[/link] website or "Search [link]targetsite.com[/link] for "Configuring feature x". You get fewer broken links this way.
    • If you use numbered figures or schematics, and don't (or can't) use the automatic figure numbering features of your word processor, minimize the times you reference the figure by number because you'll add and remove figures over time. You can start the paragraph before or after the figure with "This screenshot shows..." or "In this schematic, feature x is ...". Referring to a figure in a different topic by number is risk taking at the extreme.
    • Proof-read your content in more than one format. If you proof it only in your word processor, you'll probably miss errors that become obvious when it's displayed as HTML. I'm not sure why this is - perhaps it's to do with word positioning due to the layout and line wrap. Or familiarity with the content in the format and layout where it was originally created.

    And finally, my own hobby horse: always remember the phrase "Time flies like an arrow but fruit flies like a banana". Use "such as x" rather than "like x" when giving examples of things...

  • Writing ... or Just Practicing?

    Snakin' All Over


    My new pet snake is installed, working, and really flies. Deathly silent, yet it instantly responds to every command. It's like somebody speeded up the world. Or at least speeded up my television. And, yes, this is a follow-on from last week's rambling post about our new "Mamba" Media Center box from QuietPC.com. In fact, even the title continues the not-quite-a-song theme.

    The long and sometimes tortuous setup and installation is over. It's nestled neatly in the TV cabinet, and after a few days use it really does seem to be a superb machine - and a significant upgrade from the old I-US Media Center box. OK so most of the setup hassle was my fault (more later) because I wanted it to be on my local domain and integrated with the network. It needs to have remote Event Log access turned on, my "failed recording" monitor service installed, a custom screensaver, auto logon, and a few other tweaks.

    What surprised me, though, was the benefits from the new TV cards. The old box had only one PCI slot, whereas most modern tuner cards are PCI-E only these days so I had to choose between terrestrial (DVB-T) and satellite (DVB-S). And none supported HD. The new Mamba has a dual DVB-T2 (HD) and a dual DVB-S2 (HD) card. And, amazingly, Media Center accepted both, and tuned both of them, so that we now get all of the terrestrial and the satellite channels. You can still record from only two tuner instances concurrently (either on the same tuner card or one from each tuner card) and watch a previously recorded program at the same time. But it's wonderful to get back some old favorite channels that aren't on satellite, and to finally be able to get all the HD channels.

    Of course, the actual tuning process is still a pain, and really does need to come closer to the capabilities offered by ordinary TVs that can detect broadcast update signals and automatically retune channels that move around. Media Center has the facility to add new channels, but it never seems to fully work. In the past, when they moved channels around, I had to do a complete re-setup of all the channels - which means getting back the 500+ I don't want and had removed from the guide, and having to go through the laborious process of finding listings for channels where the channel name and the listing name are slightly different. Though maybe in the Windows 8 version of Media Center it will work better. No doubt I'll find out in time.

    The final setup process was made more infuriatingly slow by a couple of unexpected hitches. For some reason, Media Center no longer has an option to start automatically when the system restarts from cold or when a user logs on. I have no idea why this option was removed, and it seems from a web search that lots of people are annoyed about it and have found an equally large number of kludges to fix it, including creating a profile and using a batch file in the \ProgramData\Microsoft\Windows\Start Menu\Programs\Startup folder. However, another solution seems to be obvious. Create a scheduled task that runs at logon and executes the file %windir%\ehome\ehshell.exe, and set the taskbar to auto-hide.

    But the most annoying quirk was that my custom screensaver that displays details of photos never appeared. All I got was a nausea-inducing scrolling, panning, and zooming screenfull of black and white photos with odd ones occasionally appearing in colour - despite the Lock screen slideshow being turned off and my screensaver properly configured in Windows Personalization settings. I played with this for ages before finally searching the web for solutions. Most of which are totally confusing because the say to turn on the slideshow and then turn off the option to "show the lock screen instead of turning off the screen".

    I even followed the advice on one site to use gpedit to disable the Lock screen altogether, but it made absolutely no difference. After I finally gave up and went back to configuring Media Center I found the screensaver option within the Media Center interface. Which is helpfully turned on by default. The Lock screen slideshow I was trying to get rid of wasn't actually the Lock screen at all. No wonder I had problems! After turning the Media Center screensaver off my own screensaver works fine. Doh!

    I'm still not sure I'd recommend Media Center as a replacement for a normal TV to my non-technical friends, but it really is a superb system if you know something about computers, are prepared to fiddle with it, and accept the few shortcomings such as the usual need for updates and other maintenance tasks. Even the smart TVs I've seen can't compete with the full range of capabilities and flexibility of a powerful computer driving a big wall screen.

    But I have to run. Now that I've got the "Dave" channel back again, there's ten episodes of "The Professionals" from 1978 I need to watch...

  • Writing ... or Just Practicing?

    Papa Loves Mamba


    Media Center is alive and well! Yes, you can buy a proper no-noise Media Center appliance that just works out of the box, does satellite and terrestrial TV, and looks good on your TV stand. You can even watch the YouTube video on it that inspired the title of this week's rambling post.

    Our current I-US Media Center box is struggling. It's had a selection of new hard disks, and is on its second button cell memory BIOS backup battery and third video card. It sounds like a bag of bolts when it's cool, and evolves into a jumbo jet by the time it's warmed up and is recording two concurrent TV programs. Vacuuming five years of accumulated crud from the heat-pipe radiator did help a bit, but the fact that it sometimes takes three reboots to find the hard drive makes me increasingly nervous about its longevity.

    So it's being replaced by a shiny new one. Or, to be more accurate, a matt black new one - the attractive-in-an-understated-way Mamba from a local company here in the UK called QuietPC.com. It looks superb, feels really solid, and has an impressive component spec. Even the packaging is glorious, and you get all of the manuals and O/S disks you could ever want - including a magnified photocopy of the Windows product key in case your eyesight is failing and you can't read the label on the back of the case.

    So far the initial setup experience has been excellent. It comes pre-configured for use as a TV with all the proper BIOS settings, there's no junkware installed, and it's absolutely silent when running - without showing any signs of getting beyond mildly warm. No doubt the separate power supply helps, and the solid aluminum case. We'll see what happens when it's under a real-life load recording two programs at the same time as my wife is watching yesterday's episode of Coronation Street. Mind you, the O/S is on an SSD and the main data drive is a hybrid beast with SSD cache, so it should be fairly speedy.

    As usual, the hardest part of the setup is deciding on the name for the new PC. I was tempted by "Dendroaspis" (as in Dendroaspis polylepis, the black mamba tree snake), but that seems a bit too esoteric. There is a Finnish schlager band called Mamba, but their best-known songs are all unspellable words, and I'm not sure you can use accented letters in a BIOS network name anyway. I can imagine trying to solve some weird errors that might cause in my Active Directory and WSUS servers. In the end I settled on MAMBA-TV in case I forget what it is next time I'm doing my pretend-to-be-a-network-administrator thing.

    The one "not quite fully prepared" bit is Media Center itself. I specified Windows 8.1 O/S, so I had to buy and install the Media Center add-on for a few pounds. Which would have been fine except that the credit card payment system they use was broken that day, so I ended up having to open a PayPal account and then close it again afterwards (part of reducing my attack surface). At one time you could just use PayPal to make a payment with needing to open an account - but I guess (like most other sites) they want to capture your personal information to sell to advertisers.

    And how come the printer driver that Windows Update offers for my old Dell 5100CN printer is broken? Every attempt to print something just raises an error. I had this issue on another 8.1 machine, though it did start working after a few uninstall/reinstall passes. But as I'll rarely print from this machine, that's a minor issue. I installed a driver that's similar and works instead, even though it has fewer image adjustment options.

    However, my custom screensaver that displays our photos when nothing else is happening is a necessity, and unfortunately I compiled it to use .NET 3.5. I had the usual error 0x800F0906 "Download failure" when it tried to install the .NET 3.5 framework because I use Windows Software Update Service (WSUS) to manage patching on my network. The solution, and a description of why it occurs, is in this blog post.

    Now I just need to spend a day setting up the final bits and pieces, and adapting the wiring and the ventilation holes in the cabinet in the lounge where it will live. And configuring the TV setup and channel guide for the twenty or so channels that are worth watching out of the 600+ channels of junk that arrive over Free-Sat...

  • Writing ... or Just Practicing?

    my data are getting littler


    It looks like our Big Data is getting smaller. At least that's the impression I get from the exhaustive investigation carried out by the editor on our current project. Of course, "data" is actually a plural word so perhaps it's just that each datum is getting smaller. Or maybe there are fewer (not "less") of them.

    The reason for all of this shrinkage is that, according to our most recent documentation style guides, there are no capital letters in our large quantities of information. It's now only "big data" and no longer "Big Data". Is it just me that feels it somehow loses its impact when deprived of capitals? "Big Data" seems to be saying "look at me - see how huge and important I am!" But "big data" just looks like its shrinking into a corner and hoping it won't be noticed.

    And the enforced decapitalization makes some of my wonderfully delicate and skilfully crafted text sound plain odd. After I watched a documentary about how Big Data techniques are being used by many organizations around the world, I came up with:

    Police forces are using Big Data techniques to predict crime patterns, researchers are using them to explore the human genome, particle physicists are using them to search for information about the structure of matter, and astronomers are using them to plot the entire universe. Perhaps the last of these really is a big Big Data solution!

    But now that last sentence makes no sense at all, it just looks as though I had brain fade while I was writing it:

    Perhaps the last of these really is a big big data solution!

    I suppose it's all part of our ongoing drive to remove capital letters from the language - perhaps to suit the "txting" generation who don't know what a Shift (shift?) key is. My rants in An Upper Case of Indecisive Instruction, Hyphenless Decapitalization, and even I Can't Yell Any More obviously had no impact at all on our style guidance team.

    perhaps it's time i gave up my crusade, and just be grateful i have a job at microsoft writing about sql server and azure...

  • Writing ... or Just Practicing?

    Seventeen Syllable File Delete in ASP.NET


    The days when I played with ASP.NET web sites all the time have, perhaps unfortunately, gone. Now my day job has me delving into grown-up stuff such as the wonderful worlds of cloud service infrastructure, design patterns, systems and software architectural, Big Data, and even open source projects named after animals.

    So a simple task this week, as I applied my almost forgotten skills to get my custom kludged-together server status website to delete old log files, was thwarted by permission errors. And, rather strangely, it coincided with a week when I watched John Cooper Clark reciting some of his famous haiku on the BBC TV program "Have I Got New For You". Including:

    Freezing sentiment
    in seventeen syllables
    is very diffic

    (See the original version on YouTube)

    So, here we go:

    ASPNET's gone
    So all I get is denied
    When I delete files

    And even:

    It was IUSR-machine
    but now something else

    Yep, I tried setting the target folder permissions to allow the ASPNET account to delete files, but there is no ASPNET account in Windows Server 2008 R2. Instead, I tried setting the permissions for the NETWORK SERVICE group, but that doesn't work either. And there is no IUSR_[machine-name] account anymore, so that was another dead end.

    So I went off and looked for the name of the account that the Default App Pool runs under, and found one I'd never heard of before: "ApplicationPoolIdentity". Which isn't actually an account. But various blogs say there is an IIS AppPool\[app-pool-name] account that you can configure. Err, no there isn't on my server. Another blog post suggested simply changing the Default App Pool to run under the NETWORK SERVICE account, but I didn't fancy that in case I broke something else.

    Yet another blog said that ApplicationPoolIdentity is a member of the Users group, and you should just set permission on that account group. Which didn't work either. Finally I found this page, which explains that all you need to do is set the permissions on the new IIS_IUSRS account. Which worked.

    In the end it had taken two minutes to add a "Delete" button and OnClick handler to the page, but the best part of an hour finding the right information, learning about how IIS works, and fiddling with permissions. But I guess that sometimes you do have to teach old dogs new tricks...

Page 1 of 1 (5 items)