Writing ... or Just Practicing?

Random Disconnected Diatribes of a p&p Documentation Engineer

  • Writing ... or Just Practicing?

    Re-balanced and Re-routed (a.k.a. Wanna Buy An Old Modem?)


    Maybe it's because I was a boy scout when I was young that I have this need to be prepared for every eventuality. Or maybe it's my default paranoia mode that assumes stuff will just break without warning, typically on a Friday evening. It's probably why you can't move in my office for piles of spare things.

    In fact it's so bad that, when a friend phoned and asked if I could lend him an ADSL modem for testing a line that was playing up, I was able to offer him a choice of Cisco, DLink, or Netgear. Not to mention the old BT one that came with the original ADSL contract. I like to keep a spare in case the latest Netgear one I'm using dies. And, to get to them, I had to move two old 8-port switches, three 4-port ones, and a 24-port one. These are all 100 MB types that got replaced with 1 GB ones, but I keep them as spares just in case.

    Thankfully the ADSL modems weren't buried underneath the three second-hand 15" LCD monitors I bought as spares for the server cabinet when it became clear that they were becoming as rare as chocolate teapots. Though I did have to shift the boxes containing two PCMCIA wireless cards that no longer fit in any modern laptop (but you never know if they'll come in handy one day) and the vast selection of old hard drives, all less than 150 GB, which may be useful if I ever need a very small disk for something.

    Of course, almost none of these essential spares will ever get used. They are all out of date, incompatible with the kit I have, or useless. Except maybe the 15" monitors, though they'll probably have stopped putting VGA sockets on servers by the time I get round to using one. And if something does break I know full well I'll be straight onto Amazon to order the newest, cleverest, fastest, and complete with more fancy flashing LEDs than the last one, and pay for next morning delivery. Perhaps by miniature helicopter if they ever get that to work.

    Since I replaced the wireless access point on top of a cupboard in the dining room with the new Netgear one, our neighbours think we've started running a nightclub. It's got so many flashing green and blue LEDs that it lights up the room at night. There's even one that flashes alternately green and orange to indicate that it's configured in "access point" mode. Isn't modern technology wonderful?

    But the one vital piece of connectivity kit I don't have a spare for in my junk pile is the load-balancing router than joins me to my two ISPs. Since I got rid of my proxy server, the router acts as my network firewall - as well as sharing traffic between the ADSL and cable connections. And it's some years old now, so to soothe the oncoming attack of paranoia I invested in a super-duper new one to replace it (and, of course, to provide a spare). I chose the Cisco RV320 based on the extra speed and 1GB Ethernet ports. It actually cost about the same as I paid originally for the old Linksys RV42 it's replacing, and only took the best part of a month to get here (see this post).

    One of the problems with the RV042 is that the firmware is very old, and the updates won't install because I have a "Series 1" model with insufficient memory. So at least with the new one I can be sure I'm up to date in that department. Though I was a bit surprised to discover that the firmware in the new one was out of date already. Out of date out of the box! But I soon got it painlessly updated from Cisco's support site.

    Mind you, reading the release notes was a little worrying. One of the fixes in the update is, reportedly, to solve the problem of the router suffering a memory leak and locking up after it's "been running continuously for several days". It didn't say how long "several days" might be - a week? A month? I don't know about you, but I kind of expect to plug a router in, turn it on, and leave it running until I decide to buy a new one. Hopefully there are no more unresolved issues of similar gravity waiting for the next firmware update.

    Actually configuring and using the RV320 was, however, quite painless in most areas. The UI is very similar to the old RV042, though the RV320 supports IPv6 as well so I'm ready for when that comes knocking. Setting up the firewall and the custom rules was easy, and it certainly boots and runs faster than the RV042. So far it's been up for nearly a week with no problems to report.

    The one annoying thing is that the UI doesn't support the "&" symbol that I regularly use in my complex passwords. I guess it's because the login screen is web-page based, but every other router, modem, wireless access point, and device I own allows an ampersand symbol in passwords. Including the old RV042. Still, if that's the only problem I'll be well chuffed.

    I suppose the one thing left now that still needs to be replaced with a newer and more efficient (and definitely prettier) model is me...

  • Writing ... or Just Practicing?

    We're All Professional Publishing House Operatives Now


    OK, yes, I was tempted to find a title based on Slade's famous hit song Mama Weer All Crazee Now but finally caved in to the demands of the Word spelling checker. Not that this has anything at all to do with the topic of this week's ramble, which is about how home publishing has changed.

    I occasionally get requests to produce a booklet, poster, or other printed material to celebrate friends' weddings or christenings, for local events, or as publicity material for colleagues. Probably it's because they think I'm "good with computers", even though I have almost no artistic design capability. However, while producing a small booklet for some friends this week it struck me just how much easier it is now to produce professional results.

    When I first started doing things like this, very many years ago, the process involved more driving around in the car than actual computing. My dot matrix printer could never output good enough quality so all the text was created on my Mother's ancient typewriter. Text for hymns and psalms came from a hymn book borrowed from our local church. Photos came from prints done at the local chemist's shop, or by my Dad in his darkroom. Heading text was often Letraset rub-on transfers. All of these bits were cut out and mounted on card, then photo-copied at the local library.

    Of course, it wasn't long before I purchased my first mono laser printer that, in combination with a DTP application, provided endless opportunities for different fonts, text sizes, and layout. I could even incorporate the rather grainy and washed out images that early home scanners could extract from photographs. It really felt like you were doing proper publishing. Except that, without some artistic ability, everything came out looking like a church newsletter. Which was OK when I was actually doing a church newsletter, but a bit boring if it's to promote the local gardening club show.

    At times, in the days when I actively wrote and sold my own software, I would create professional leaflets. The layout and design were usually copied from something I saw in a magazine. The big problem was getting the design from screen to paper with the kind of quality I needed, and in large volumes. Luckily the DTP program I was using then could generate three-color print files that my local print shop could feed into their huge print line. They cost a fortune, and I doubt ever paid for themselves in increased sales, but they looked beautiful.

    So this week, as I was creating a small commemorative booklet, I realized just how easy it has all become. Microsoft Publisher contains a host of attractive design templates, and there are more online, so generating the outline was easy. Most of the text was provided by the friends, sent by email so I didn't even need to type it in. And they emailed the digital colour photos taken on their phone, which I could quickly tidy up, crop, and adjust in Paint Shop. The words of the hymns, psalms, and songs they wanted are available on the web, so I didn't need to type these in either.

    And then, before committing it to print, I generated a PDF and emailed it over so they could check it. Adjustments to content and layout are easy, and after three or four electronic interchanges I could simply dump the whole thing as a print job to my double-sided color laser printer; onto photo card for the cover and nice buff-colored pages for the inside. The result is startlingly professional, and all without ever needing to go out of the house.

    Except that I had to go out to a local print shop because I still haven't got round to buying a long-arm stapler. Maybe the next leap forward will be home printers that can fold and then ultrasonically bind the pages together...

  • Writing ... or Just Practicing?

    I Wished I Was ... in Iceland


    Birthdays are usually celebrated with a day off work, perhaps a trip to a garden centre, or just a lazy afternoon with a good book. However, as the milestone 60 loomed it was decided for me that I was going to have a week's vacation and go somewhere exciting. Somewhere that really had that "Wish you were here" effect. Trouble is, most of it turned out to be "I wish I was a..."

    For example, this day I wished I was a surfer:

    Dyrholaey beach and cliffs

    And this day I wished I was a mountain climber:

    Solheimajokulsvegur glacier

    On this day, I wished I was a rally driver:

    Near Gulfoss on Road 30

    And on this day I wished I was a geologist:

    Dyrholaey caves

    And, of course, on this day I wished I was an astronomer:


    The Northern Lights seen from near Hella

    But at least, on this day, I could just relax and soak up the steam and sulphur fumes:


    The Blue Lagoon, Grindavik

    Iceland is a really amazing place. Especially as, since I'm still suffering from the after-effects of a spine injury that makes long trips and walks difficult, it's only two and a half hours by plane from a small local airport and I had a rental car waiting. And driving there is easy, although it's on the wrong side of the road - until you decide to explore a little. Driving on solid-packed ice, or gravel tracks with 1 in 3 inclines, is fun. Thankfully the car was 4-wheel drive with studded tyres!

    Iceland is also an ideal destination for those that have a fetish for waterfalls. This is the famous one:


    But we managed to find plenty more:


    Seljalandsfoss and Merkifoss


    So, yes, we did the usual tourist things. Bathing in the Blue Lagoon hot springs (where they have to keep adding cold water to keep it below boiling point). Listening to the waves echoing round the caves at Dyrholaey and marvelling at the incredible rock formations. Driving miles over rocky unmade roads to see a glacier (the bits that break off do, in fact, look rather like a Fox's Glacier Mint that been loose in your pocket for a few weeks). Driving the "Golden Circle" tour to see the lakes, Gullfoss falls, the geysers and hot springs at Geysir:

    Some geezers looking at a geyser at Geysir

    And looking across the Mid Atlantic Ridge where two tectonic plates are gradually tearing Iceland apart (but there's a pretty church to look at):

    Tectonic plate boundary in Pingvellir National Park

     More Pingvellir National Park

    Iceland also has the most amazing sunrises and sunsets in wintertime:

    Sunset near Hella, South West Iceland

    And it's nice to know that the people have a sense of humour as well:


  • Writing ... or Just Practicing?

    Gimmie The Code!


    It seems like a question that has an obvious answer: How should you show code listings in guidance documents? I'm not talking about the C#/VB/other language debate, or whether you orient it in landscape mode to avoid breaking long lines. No, I'm talking about the really important topics such as what color the text is, how big the tabs are, and where you put the accompanying description.

    We're told that developers increasingly demand code rather than explanation when they search for help, though I'm guessing they also need some description of what the code does, the places it works best, and how to modify it for their own unique requirements. However, copy and paste does seem to be a staple programming technique for many, and is certainly valid as long as you understand what's going on and can verify its suitability. I've actually seen extracts of code I wrote as samples for ASP 2.0 when it first appeared (complete with my code comments) in applications that I was asked to review.

    But here in p&p a lot of what we create is architectural guidance and design documentation designed to help you think about the problem, be aware of the issues and considerations, and apply best practice principles. As well as suggesting how you can implement efficient and secure code to achieve your design aims with minimal waste of time and cost. "Proven practices for predictable results", as it says on the p&p tin.

    But even design guidance needs to demonstrate how stuff works, so we generally have some developers in the team who create code samples or entire reference implementation (RI) applications. These are, of course, incredibly clever people who don't take kindly to us lowly documentation engineers telling them how to set up their environment, or that the code comments really should be sentences that make sense and have as few spelling mistakes as possible.

    In addition, Visual Studio has a really amazing built-in capability that we've so far failed to replicate in printed books. It can scroll sideways. These esteemed developers often prefer to have four or more space character wide tabs to make it easy to read the code on screen (the Visual Studio default is four). By the time you are inside a couple of if statements, a try/catch, and a lambda statement, you're off the page in a book. Two spaces is plenty in a printed document (where we have to replace the tabs with spaces anyway), but I've never yet persuaded a developer to change the settings.

    And now Microsoft mandates that we have to use the same colors for the text in listings as it appears in Visual Studio (I guess to make it look more realistic, or at least more familiar). The old trick of copying the code into Notepad, editing it, and then pasting it into the document no longer works. But copying it directly from the Visual Studio editor into a document is painful because it insists on setting the font, style, margins, and other stuff when I just want to copy the colors. Yet if I do Paste | Special | Unformatted Text in Word, I lose the colors.

    And then, when I finally get the code into the document, I need to describe how it works. Do I dump the entire code for a class into a single code section and describe it at the start, or at the end? If the code is a hundred lines or more (not unusual), the reader will find it cumbersome to relate parts of what is likely to be a long descriptive section to the actual code listing. I can break the class down into separate methods and describe each one separately, but often these listings are so long that I have the same problem.

    And, of course, explaining how the methods relate to each other often means including an abridged version of some parts of the class or one of its methods, showing how it calls other methods of the class. But do I list these methods first and reference back to them, or explain the flow of execution first with the abridged listing and then show the methods that get called?

    Typically I end up splitting the code into chunks of 30 lines or less (about half a printed page) and insert text to introduce the code before the chunk and text to describe how it works after the chunk. Something like:

    The GoDoIt method shown in the code listing above calls the DoThisBit method to carry out the first operation in the workflow. The DoThisBit method takes a parameter named thisAction that specifies the Task instance to execute, as shown in the following code listing.


    The DoThisBit method first checks that the task is valid and then creates an instance of a ThisBitFactory, which it uses to obtain an instance of the BitHelper class... and so on.

    After going backwards and forwards swapping code and text, breaking it up into ever smaller chunks, and trying to figure out what the code actually does it's just a matter of editing the code comments so that they make sense, breaking the lines in the correct places because they inevitably are longer than the page width, and then persuading the developer to update the code project files to match (or doing that myself just to annoy them).

    Sometimes I think that putting code listings into a document takes longer than actually writing the code, though I've never yet managed to convince our developers of that. But I've been doing it for nigh on twenty years now, so I probably should be starting to get the hang of it...

Page 1 of 1 (4 items)