Writing ... or Just Practicing?

Random Disconnected Diatribes of a p&p Documentation Engineer

  • Writing ... or Just Practicing?

    Drowning in Drought


    Perhaps all countries, states, and regions are naturally capital-city-centric, but it's not often I am brutally reminded of that fact here in Ye Olde England where nowhere is very far away from anywhere else - at least in geographical terms. But, here in the wilds of rural Derbyshire, it's becoming increasingly clear just how far away we are in practical terms from the rest of the country.

    Reading the newspaper, it seems like the world is about to end because of the most severe drought for fifty years. Reservoirs are empty, rivers have dried up, and it's so bad that our local water company is actually selling water to others elsewhere in the country. I read last week about how Severn Trent is pumping water into a local river that eventually feeds into the River Trent where Anglian Water is sucking it out again. I'm not sure how they know which water is theirs, or whether there'll be floods if they don't pump it out quickly enough.

    Of course there's already a hosepipe ban on now in the majority of the country, with the most severe restrictions ever. They say that there'll soon be standpipes in the street and water rationing unless people start bathing in just half an inch of water. You'd think that we lived in the middle of a desert.

    And every day there's a new crisis. Boat cruise companies will go out of business because the canals are closed. Public parks will become waste grounds as all the trees and bushes wither away. There'll be hundreds killed on the roads because cars will be so dirty you can’t see them. Garden centers will go bankrupt because nobody will buy plants. And then, when it does rain, there'll be flash floods because the ground is baked hard.

    So while most of the country is reported to be drowning in both debt and drought, here in our glorious little haven of tranquility we're drowning in a lack of drought. Last December was the wettest for years, and it rained for most of March and all of April. At Easter it snowed. My lawn in like a quagmire, my fishpond is overflowing, and you need waders to walk through the woods next door. At one point recently it was raining at a rate of five inches per hour, and we even had hailstorms twice last week. Someone wrote to the letters page of my daily newspaper yesterday to ask if this was the wettest drought since records began.

    Mind you, I did hear that our local recreation center is doing its bit to help. Due to the water shortage, they've closed two lanes of the swimming pool.

  • Writing ... or Just Practicing?

    Meandering Meanings


    I bet you didn't know that the word "Wikipedia" actually means "fast child". And that the towns of Pendle Hill in Lancashire and Bredon Hill in Worcestershire both have names that mean "hill hill hill". No, neither did I until I bought Mark Forsyth's book "The Etymologicon" (which, incidentally, means "a manual for one who studies the history, and change in form or meaning, of words").

    Mark writes a fascinating blog about etymology called The Inky Fool, and you can find links to the book on his blog. If, like me, you have a fascination with where words come from, how their meanings change over time, and how they relate to each other (and, in my case, how you can even make up your own new ones) then you really do need to buy a copy of this book.

    The subtitle is "A Circular Stroll through the Hidden Connections of the English Language", and it certainly seems like it does both the hidden connections bit (which must have required an immense amount of research) and the circularity (especially as the final paragraph ends with "continued on page 1").

    To give you a flavor of the style and content, I'm sure Mark won't mind me quoting some extracts from the very start, where he discusses what a book actually is. And, of course, due to the circular nature of the connections, the very end of the book does the same to complete the iteration:

    "This is a book. The glorious insanities of the English language mean that you can do all sorts of odd and demeaning things to a book. You can cook it. You can bring a criminal to it, or, if the criminal refuses to be brought you can throw it at him."

    From here, the topics move swiftly to "bookmakers" (who used to make books, but now take bets), to "a turn-up for the books" (which is really about bookmakers and not about books at all), to throwing stones at chickens in France.

    Later, there's a section on frequentative suffixes that explains how people get to be gruntled (by grunting very often) before they can be disgruntled, one that discusses where the Cybermen came from (no, it wasn't Earth's twin planet Mondas), and one about how Bluetooth connectivity wouldn't have been called Bluetooth if the guy who invented it hadn't been reading about Vikings at the time.

    And, most amazing of all, an explanation of why Winston Churchill's demands for wartime secrecy meant that tanks (the big iron things with tracks underneath and a gun on the front) didn't end up being called "carriers", or even "landships".

    Meanwhile, the book will also tell you what the thing that used to be a "taximeter cabriolet" actually is today, and how the Von Trapp family were cruelly deceived because "do" is not a deer, a female deer, and "re" is not a drop of golden sun.

    But if you want to know why Wikipedophiles are taking advantage of fast children, and why some people living in Lancashire and Yorkshire can't think of better names for their hills, you'll just have to buy a copy of the book...

  • Writing ... or Just Practicing?

    It Feels Like I've Been Snookered


    Probably the most memorable comment from a snooker commentator was Ted Lowe during a Pot Black match in the late 1960s. Acknowledging the fact that in those days many viewers didn't have a color television, he helpfully noted "for those of you watching in black and white, the pink ball is next to the green". Question is: can I stay on the ball when I'm writing in black and white?

    While Ted's comment might initially seem a bit daft, it was actually helpful. With the green ball on its spot at the baulk end of the table, any snooker fan would know which ball he meant. Unfortunately, the same can't be said of my current skirmishes with the new Microsoft Accessibility Standard (MAS) that's just come into operation. Yes, it's a good thing that we now have a fully documented and very necessary standard that details how to achieve optimum accessibility for all users of our content. But putting it into practice here at p&p is an interesting exercise.

    The overall rule is simple enough: all documentation must be usable by every type of reader, using every type of input and output device, without mandating a specific type of hardware. In other words, we must not force a user to use a mouse or keyboard (they may be using a touch screen device or some other type of input device), or any type of screen or output device (they may be using a screen reader designed for those with low or no vision).

    For many years before becoming a 'Softie, I specialized in conference presentations and articles related to maximizing web site accessibility. Web pages that work fine with no script support (such as in all types of screen readers), and which work without depending on color - a bit like Ted Lowe's snooker conundrum. In fact one of my slide decks had a title page consisting of six large buttons in various shades of gray, with an instruction below that said "Press the green button to start the presentation".

    So I should be well versed in the technicalities of accessibility, but it's not so easy when you come to put it into practice with our relatively complex documents. In many cases, the stuff I create is architectural and developer guidance that talks concept and implementation, so it's just a case of text and schematics. OK, so the schematics aren't usable by those with low or no vision, but we do explain the contents in the surrounding text as best as we can. And we never depend on colors because our guidance is typically designed to be printed in monochrome as a book, as well as HTML on MSDN.

    However, my current project is a series of Hands-On Labs related to the guide Building Hybrid Applications in the Cloud on Windows Azure. These are, of course, pages and pages of procedures with steps consisting of "click the Whatever button" and "press the Whoknowswhich key". Except now they aren't because we can't do this any more. It contravenes the MAS rules. I guess it always did, but we never really noticed because the labs are aimed at knowledgeable developers who we assume are familiar with Visual Studio and know the equivalent key presses, menus, and shortcuts.

    I wondered if we would be exempt because we're just using Visual Studio, and the people who write the docs for it would have covered all the accessibility bases already. But that's not a reasonable approach - we need to make sure that we abide by the rules and offer the most accessible content to the widest range of users.

    One solution suggested by MAS is to include all options for each user action, such as "Press Alt-Whatever followed by the Another key (or right-click and then click Whatever, or select Whatever from the Thatone menu)". But imagine how that will pan out when there are twenty steps in the procedure where each one requires three user actions, and Visual Studio has four different ways of carrying out each action.

    Another alternative is to provide a table of equivalent actions. We'd need five columns, one each for mouse, keyboard, shortcut menu, shortcut key combination, and screen tap; and there'd be a row for every action for the whole lab. So the table could easily run to several pages, and is unlikely to be anywhere near useful.

    We finally decided on the third option: be non-specific. Use words such as "select" and "choose" that don't imply any specific input device or method. For example, "Select Yes please and then choose OK". The selecting could be with a mouse scrolling a drop-down list, arrow keys, tapping with a finger, or through a voice-actuated screen reader device. The OK could be a mouse click, the Enter key, a screen tap, voice recognition, or the equivalent in any other configured input device.

    However, there's another issue as well. We can't use relative visual position as a guide to a task because some devices may not display the screen contents in the same way, or may be audio screen readers. Therefore, instructions such as "In the left pane of the screen, click Whatever" or "Select the Another option below the textbox" won't comply with the rules. So some judicious re-wording is required to indicate which control we mean when there are several similar ones.

    As I worked on the Hands-On Labs last week, I decided to make life easier for users by highlighting the required button, textbox, list, or option with a big red circle on the related screenshot for each step. That will make the newly added vagueness easier to cope with, though it's hard to see how it will help users with low or no vision. And I've yet to fully grasp the validity of using words such as "look" and "see" when guiding users through the steps and actions.

    But it will certainly be interesting to discover how long it takes me to get used to not automatically typing "Click" at the start of each step...

  • Writing ... or Just Practicing?

    Who Ate All The Pi?


    Here in the UK, you have to wonder where our next generation of developers and programmers will come from. What has changed over the past twenty years that seems to be destroying the curiosity and passion we used to have for learning about computer language theory, algorithms, and programming techniques? Maybe it's a topic that is just too remote from modern life and young people's aspirations?

    All this contemplation came about after reading about the new Raspberry Pi experimental computer. When I first heard about this I expected something like the old kits I used to play with back in the 80's; a row of lights that showed the binary result each time you entered a machine code operator using the row of switches and pressed the "Go" button. But things have come a long way since then. The Raspberry Pi has an O/S and UI, a development environment, and even powerful audio and video capabilities. It's pretty much a complete computer.

    The idea is that kids will learn about computing using this, and older (post-school) users will take it up as a way to learn more about the internal working of computers and programming languages. It's an up-to-date version of the early home computers from Sinclair, Atari, Oric, Commodore, and others; a cheap and easy way to get into the real world of computing, rather than the esoteric and non-technical ICT (Information and Communication Technologies) stuff they teach in schools today.

    I guess that, as a computer freak for more years that I care to recall, I find it hard to understand why kids don't seem to have the same passion for hardcore computing topics such as experimenting with different languages and learning about algorithms and programming techniques. Instead, they get taught how to use word processors and spreadsheets, and how to express themselves through email and social networking. Vital skills for the future, I agree, but hardly a way of raising their interest in the fascinating world of real computing.

    I suppose that today's computers, tablets, phones, and other devices are more suited to producing results or integrating with lifestyles than being a useful platform for experimentation. Even writing programs has been reduced to simple drag/drop/configure tasks through the application frameworks and builders now in common use. Do you need to understand algorithmic programming and proof any longer? Do the tools remove the need for the basic skills and knowledge of programming logic and construction?

    What is really startling, however, is the revelation in the article I was reading that out of 27,000 teachers who qualified in 2011 here in Britain, only three have degree in computer science. Less than 0.01 percent of new teachers have enough interest in "real" computing technologies and techniques to study it in depth. I guess there are thousands who can teach kids how to use Microsoft Word and send email, though I suspect that a lot of kids can already do that without needing lessons. And I suppose there are plenty of artistically-oriented teachers that can cover computer-based multimedia studies and creative activities. But who will kindle the desire to "know how it works" we had; something that surely must still reside in today's kids?

    The aim of the Raspberry Pi project is "to bring real computing back to the classroom". The question is, who will define what "real computing" is today - and what will they decide?

  • Writing ... or Just Practicing?

    The Rule of "It Depends"


    It seems odd that, in order for a rule to be valid, there has to be an exception. According to the well-known phrase "the exception that proves the rule", this must be the case. Yet watching a TV quiz show the other week, I was amazed to discover that one of the rules I've applied most days of my working life as a writer is actually completely wrong.

    If you went to school more than a few years ago, you'll no doubt be familiar with the spelling rule "i" before "e" except after "c". For all my working life this rule has allowed me to correctly spell words such as "receipt" and "ceiling". Yet, for some unaccountable reason, I never thought of applying it to words such as "leisure" or "being". They just naturally have "ei" in them.

    And I assume that's why I always wonder about writing "friend" instead of "freind." I suppose we're back to the "ghoti" (fish) conundrum here. Though now I use Word all the time, I end up spelling words like this (friend, not fish) accurately just because Word automatically corrects them. Try typing "freind" with Word's AutoCorrect feature turned on (the default setting) to see what I mean...

    Anyway, the point about this quiz show and the "i" before "e" rule is that it is actually a non-rule. Whereas there usually needs to be at least one variation that proves a rule, it seems there are twenty one times as many words that break this rule as there are words that comply with it. At the last count, there were 489 words in the Oxford English Dictionary that contain "ei" without a preceding "c". In fact they say the rule is so useless that they no longer teach it to kids in school. Perhaps we can look forward to recieveing emails from our grown-up kids telling us how much our new grandson Kieth now wieghs, how the christening party went, and how at the hieght of the celebrations somebody managed to put their foot through the bedroom cieling.

    But I guess our own industry is just as vague about defining general rules for the design and implementation of software. As I've discovered (and ranted about in the past), almost any question you ask a software expert about almost any topic of architecture or code results in an answer that starts with "Well, it all depends on ... [insert a complex mix of conflicting circumstances here]." Try it yourself. Next time you are at a cocktail party and find yourself standing next to a software designer, ask them if Command Query Responsibility Segregation will make your semi-normalized Domain Driven Design model easier to implement in a multi-node, clustered, cloud-hosted solution.

    Or how many developers are required to change a light bulb (from a search of the web, it seems the answer is "none" because it's actually a hardware problem).

Page 1 of 1 (5 items)