|
|
|
posted at
11:36 AM
|
trackback
|
|
link
For fun the other day, we came up with terms of venery for the many species that can be found in the world of IT. Herewith our list. Can you come up with more?
A compilation of programmers
A unit of testers
A click of QA engineers
A spec of program managers
A package of builders
A deployment of SysOps -or- A distribution of SysOps
A bundle of network engineers
A row of DBAs
An interface of UX designers
A lab of usability testers
A snarl of IT admins
A triage of Helpdesk engineers
A pixel of graphic artists -or- A sketch of graphic artists
A meeting of managers
A retreat of general managers
A scribble of writers -or- A sheaf of writers
A revue of editors (haha) -or- A scrabble of editors
A project of interns
An oversight of auditors
A tweet of tech evangelists
A quarrel of patent lawyers
[categories]
writing, technology
|
posted at
09:02 AM
|
trackback
|
|
link
 I've lived through similar scenarios in the software industry multiple times: the company devises a new technology—not just an update to your already successful releases, but a new approach. As with the record company, tho, it's rarely easy to simply pull the plug on your old stuff, since many of your customers are heavily invested in your old technology.
If you're the documentation person under these circumstances, you have a tricky job. If the new technology is sufficiently different, you can create a brand-new documentation set from scratch for the new technology. (The documentation sets for record players and CD players have very little shared information.)
But it's not always that clean a break. Consider a database product where the new technology is an innovative search syntax. Everything else about the database (storage, backup, etc.) is the same; you just have a new way for users to craft their queries. Moreover, the old query syntax still works.
Too often, what ends up happening is that writers add a section to the existing documentation that describes the new technology. This "solves" the problem. Hey, now we have two technologies! We've documented both of them!
But what do your users actually need? - All users need to understand that there are two technologies, and why, and how users should choose between them. In your compare-n-contrast, you have to be careful not to trash-talk your old technology (in spite of what your engineers and early adopters probably think); a few years ago, you spent a lot of effort to convince your users how great that technology was.
- Existing users need to understand what the new technology means for them. Do they have to upgrade? What does it mean for their existing investment? How long can they continue to use the old technology?
- New users (probably) need to be directed to the new technology. They also need to understand that there's an existing body of knowledge about the old technology (for example, documentation and articles and books and forums) that could mislead them if they're not aware of the different versions.
You can accomplish this easily—well, "easily"—in some sort of introduction or overview. But you also have to think about how to help users who drop into your documentation from unexpected places—say, from a web search. Your existing documentation is of course all about the old technology. The descriptions are about the old stuff; if there are examples or illustrations, they're probably about the old stuff. Existing customers will probably continue to use the old technology and will still need documentation for it, so you can't just rip out the old stuff and replace it with new docs.
You might consider reviewing every page of your existing documentation where the old technology is featured (for example, every page that shows query syntax). Then you have to ask whether you replace the existing examples with new ones, or whether you add corresponding examples of the new syntax. In the latter case, how much explanation do you need in order to make sure readers understand that there are two syntaxes?
As I say, I've lived through this. As of last year, the technology I worked with (ASP.NET) had three distinct approaches to creating websites. We had a heck of a time even crafting the message of how to select between them.
And the idea of visiting each page (page design, database access, deployment, etc.) and updating it for all three technologies—or creating technology-specific versions of each of these stories—was a challenge indeed. (They've since added a fourth technology fourth and fifth technologies.)
The evolution of a product is of course exciting for users, who get new and improved technology to work with. But unless a new technology represents a completely clean break with the old, and unless you can create separate, standalone doc sets for each technology, in some ways the documenter's job can actually be harder than it is for the engineers.
[categories]
technology, writing
|
Thursday, 31 January 2013
|
Rocket Science for Beginners
posted at
10:31 AM
|
trackback
|
|
link
Keep it secret, keep it safe: A beginner's guide to Web safety
I was initially interested, because although I am more-or-less conversant with the basics of safe browsing—using wifi safely at a coffee shop, for example—there are certainly other people in our household who might value some tips "for beginners" about how to use the web safely.
Then I actually read the article. Here are a couple of examples of advice for those beginners:Clicking the browser's padlock icon while visiting Facebook, for example, gives us the most relevant information about the certificate and its encryption algorithms: the certificate has been signed by VeriSign and the connection uses TLS 1.1 with 128-bit RC4 encryption.
[...]
If you want to roll your own [VPN] server, you can use free software like OpenVPN (or, for Mac users, the VPN server included in the $20 OS X Server package). Frankly, I'm not really sure how grateful my wife would be to learn these things.
 Obviously, the issue has to do with the term "beginner." It's not actually clear to me who exactly the author had in mind as a beginner, but it's not my wife, or my kids, or a bunch of other people who are perhaps not quite ready to examine the certificate chain for the current session.
Scene 2. The other day I was working on a programming problem and someone handed me a working example in the programming language named Python. I don't, er, speak Python, so I had to set up my computer with the requisite tools. In the process of looking for instructions about this, I ran across an article that included the following gems:You want to use Python on a Windows 7 machine but you don't know what you're doing. What you do know is that in order to go anywhere and do anything you've got to install packages. Or maybe you don't even know that yet. andThe good news is: it's easy.
There is no bad news. andSee all that stuff flying by? Forget about it. I was more than willing to overlook the perhaps too-flippant tone because the article in effect carried out its promise to document the process for (real) beginners.
So. If I see a title that involves the phrase "for beginners," I have a specific idea of what the reader is expected to know (or not know). Perhaps the author of the ArsTechnica article knows something about the audience for articles in that publication such that when he writes "for beginners," he actually means "really technical, but new to this thing." That's quite legitimate, if sometimes a little misleading. (One of the problems I had in finding information about Python "for beginners" is that the assumed starting point for most of the information I found was someone who already knew programming, operating systems (often Linux), tools and technologies (.tar), etc.)
As with any piece of technical writing, you need to have a clear sense when you start of who you're talking to. For a lot of writing, it's not a bad idea to actually lay this out at the beginning of your piece. And if you're going to use a term like "beginners," it seems like you have more obligation than usual to actually indicate what you mean by that.
[categories]
writing, technology
|
posted at
12:19 PM
|
trackback
|
|
link
I taught a class over the last couple of Saturdays and told folks they could send their homework to me at mike@mikepope.com. On Wednesday I got an email from a student telling me that the email address I had handed out wasn't working. (The student had managed to find me via a different channel, thank goodness.) I tried sending an email to the address I'd distributed, and sure enough, back it came.
The keeper of my domain (mikepope.com) is GoDaddy. As part of registering my domain and getting them to manage it, I'd gotten "free email forwarding" for the domain. When someone sends email to the mikepope.com domain (e.g., mike@mikepope.com), the message is forwarded to my other, "real" email addresses.
Some months ago, I started getting a steady volume of messages to my real email addresses that told me an email had bounced, often with the message "invalid recipient address." The strange thing was that these were bounces for emails that I had never sent. This turns out to be a well-known problem—spammers forge a From address on their spam mail (they don't want you to reply, they just want you to click the link in the email they send). Spammers use many, many different forged From addresses in their attempts to get around spam-detection strategies. Apparently the mike@mikepope address had fallen into the hands of just such a spammer.
I did investigate a bit whether there was anything I could do about this; I didn't want my ISP (Comcast) to think I was originating these spam emails. But nothing can be done, so I stopped worrying about getting these oddball bounces. In any event, the volume of these no-recipient bounce messages had tailed off recently, tho I didn't think much about it at the time. (I think I reckoned that Comcast's spam detection was filtering them.)
 Then came the incident with the class and the frustrated students, so I had a look. It turns out that I had misunderstood something about how email was handled for mike@mikepope.com. Yes, I've set up forwarding for that address at GoDaddy. However, I also have—I don't know whether I actually intended this or whether it was a feature of my domain hosting—an email account at GoDaddy. And over the last few months, that email account had been filling up with lots and lots of these bounce messages for spammers. In fact, the mailbox had reached capacity. As a result, when students sent me email, they were in turn getting a legitimate bounce message from mike@mikepope.com, which said:<mike@mikepope.com>
child status 100...The e-mail message could not be delivered because the user's mailfolder is full. Because I didn't understand that I had an actual mailbox at GoDaddy, this didn't make sense to me at first. But after hacking around in GoDaddy's wretched dashboard, I eventually got to the actual email mailbox that I didn't really grok that I had. The Inbox had hundreds (thousands?) of the spam-related bounce mails, along with a few legitimate emails. Oh and look, a nice red graphic told me I'd reached 100% of my capacity. (GoDaddy's response to this problem was to offer to sell me more space.)
I bulk-cleared the Inbox and Trash and now it all works again. Who knows how many legitimate emails I've missed because they got bounced from mike@mikepope.com and the sender didn't or couldn't try again. Hopefully not many.
Now I have to figure out what to do to prevent this in future. One way would be to monitor this GoDaddy-hosted mailbox. I might also just get rid of the GoDaddy mailbox (and keep just the email forwarding), since as far as I know I don't need it. I hesitate on this latter only because managing anything via the GoDaddy interface is ... not fun and not easy. And I don't want to break the part of the system that does work, namely forwarding. Ah, well—it wouldn't be a real website unless I had to screw with it all the time. :-)
[categories]
technology, personal
|
posted at
06:34 PM
|
trackback
|
|
link
Ctrl+Enter. By default, this keystroke performs a Send operation, and boy, can that be annoying.
Turns out there's an easy fix. (To Outlook, not to your typing.) I got this from someone on the web, I think it was. (Alas, I don't remember, so my apologies to whoever that was.) In Outlook, click File > Options. In the Options dialog box, click the Mail tab, then scroll down to Send messages and uncheck (Ha! Take that!) the option CTRL + ENTER sends a message. Here's a picture:
This works for Outlook 2010 for sure, and probably (?) for Outlook 2007. I can't speak for earlier versions.
[categories]
technology
|
Wednesday, 3 October 2012
|
Guard cat on duty
posted at
06:39 AM
|
trackback
|
|
link
To: [whole group]
From: [senior developer]
Subject: I love kittens because they're fluffy
This would be one of yer more wtf new-job moments. A few minutes later we got this:
To: [whole group]
From: [senior developer]
Subject: re: I love kittens because they're fluffy
I stepped out of my office for 30 seconds and I was in the office next door!
 There was a reasonable explanation for all this, as it turned out, which involved security. Every company has security policies for computer use, of course, and larger companies might have dedicated IT folks who enforce such policies. One way they might enforce policies is to perform security audits of people's workspaces. For example, has someone written their password on a yellow note and stuck it on their monitor? Fail.
Another policy that the security folks might audit is the practice of locking your workstation when you step away from your desk. Obviously, if you walk away from an unlocked machine, anyone can jump on your computer and start hunting around for sensitive information.
Even a vigilant security audit team, however, can't watch everyone every minute. But I happen to work with a bunch of security-minded developers, so a protocol emerged that if they could catch you with your workstation unlocked, you were fair game to have a fluffy-kitten email sent from your computer. Our senior developer guy, in spite of his protestations, had been caught sneakily when he stepped out for the quickest of conversations.
I got filled in on this by another guy in the group (in fact, the guy who'd gotten the drop on the kitty-loving developer). He explained that the group—as I say, a security-minded bunch—had started it as a kind of game in order to help enforce security policy. The remarkable thing, he noted, was that once the kitty emails started, compliance with the rule about locking workstations had gone from around 10% to over 90% in just a few weeks.
Everything about this business amused me, from the kitty theme itself to idea of security enforcement by (mild) peer pressure. And it's certainly effective—you can bet that before I run to the kitchen or step next door for a wee meeting, I make sure that I've locked my computer.
[categories]
work, technology
|
Tuesday, 11 September 2012
|
Key remappings in Word
posted at
04:55 PM
|
trackback
|
|
link
I've found that it speeds up revisions tremendously to map keyboard shortcuts to the commands in Word that you use to find, accept, and reject revisions and comments. As a bonus, I don't like that the traditional Find key in Word 2010 is mapped to some sort of Navigation pane (where traditional Find is available under Advanced Find). So I map Ctrl+F as well. As I say, this is primarily for my own reference.| Task | Command | Key mapping |
|---|
| Display Find/Replace dialog box | EditFind | Ctrl+F |
| Find next revision or comment | NextChangeOrComment | Ctrl+Shift+F |
| Accept current change | AcceptChangesSelected | Ctrl+Shift+A |
| Reject current change | RejectChangesSelected | Ctrl+Shift+R |
[categories]
technology, writing
|
posted at
07:54 AM
|
trackback
|
|
link
The [Language] Programming Language
The Ruby Programming Language, The SQL Programming Language
The authors are really hoping you'll think that they've written their language's version of The C Programming Language, aka K&R. Not much chance that their books are a slim 250 pages like the original, eh?
[Language] in a Nutshell
Python in a Nutshell, VB & VBA in a Nutshell
Reference docs.
Programming [Language] or Pro [Language]
Programming Visual Basic 2008, Pro ASP.NET MVC Framework
This is a Serious Book, "by programmers, for programmers." Bound to be fat in order to accommodate the many heavy thoughts it contains.
The Definitive [Language]
JavaScript: The Definitive Guide, The Definitive Guide to Linux Network Programming
This book is big, and it's comprehensive, and it's probably not for programming novices, unless those beginners are unusually persistent or unusually smart. Likely to be good for experienced programmers, tho.
[Language]: The Good Parts
Java: The Good Parts, PHP: The Good Parts: Delivering the Best of PHP
You already know the language. Dammit, Jim, now learn how to use it right.
Learning [Language] or Beginning [Language] or [Language] for the Beginner
Learning ASP.NET 3.5, Beginning C# 3.0, Python Programming for the Absolute Beginner
The book is for the novice, tho it may not be clear if it's for a novice to programming or just to the language. Whether the book actually can teach novices is ... well, let's say it depends on the author.
Head First [Language]
Head First jQuery
For novices (see Learning et al, above), but claims to use unique pedagogical techniques that are "brain friendly." That might depend on your brain, tho.
The Art of [Language]
The Art of Unix Programming, The Art of Assembly Language Programming
The author wishes to invoke the spirit of Donald Knuth's The Art of Computer Programming and aspires to that level of comprehensiveness. Or perhaps they're inspired by Julia Child and Mastering the Art of French Cooking. (Was Knuth inspired by Julia?) Either way, is it possible that the author has an unusually large, er, ambition?
The Joy of [Language]
The Joy of Clojure, The Joy of Patterns
Joy in the title does not mean, I think, that the book adheres to the assume-nothing philosophy that Irma Rombauer made famous in The Joy of Cooking, just that the author enjoys the subject.
[Language] Cookbook
JavaScript Cookbook, ASP.NET MVC 2 Cookbook
Little algorithmic bites for easy and delicious results.
Idiot's Guide to [Language] or [Language] for Dummies
Complete Idiot's Guide to C++, COBOL for Dummies
Yeah, well. As an aside, I cannot prove this, but I think that the original Idiots book was John Muir's classic How to Keep Your Volkswagen Alive: A Manual of Step By Step Procedures for the Compleat Idiot, which was a milestone not only in shop manuals, but in technical writing withal.
Teach Yourself [Language] in [Time Period], Learn [Language] in [Time Period]
Teach Yourself C in 24 Hours and about 4 million more
This book is not just for beginners, but for people who don't even really know what they're getting into. The false promise of these titles once inspired Peter Norvig to pen Teach Yourself Programming in Ten Years, which is more like it.
[Language] the Hard Way
Learn Ruby The Hard Way, Learn Python The Hard Way
The whole "in 24 hours" nonsense (and maybe Norvig's reaction) have inspired Learn [Language] the Hard Way aka LCodeTHW. These books eschew shortcuts and oblige you to type in, character by character, the examples that they provide. A kind of programmer's version of Because It Builds Character.
[Language] for Evil Geniuses
Programming Video Games for the Evil Genius
"Hey! Programming is FUN!!"
And then there's the weird stuff ...
Learn You a Haskell for Great Good!
No one seems entirely sure where this title came from, but people have picked it up (e.g. re: refactoring and Flexbox) and we'll be seeing more of it, I predict.
why's (poignant) Guide to Ruby
Foxes and chunky bacon. A, er, unique approach to programming books. Nothing else quite like it for the time being.
[categories]
technology, FridayFun
|
posted at
12:06 AM
|
trackback
|
|
link
This actually is quite amazing, if you think about it. I can start up a CD that I distinctly remember buying 27 years ago, and WMP figures out what it is and then goes out to ... somewhere ... to bring back album art and a track listing. (Try that with your vinyl or cassette tapes, ha.) When I was working my way through the pop/rock and jazz CDs, I don't think it ever failed to find the right CD and track listing. I think the only flaw I ever found was that it would retrieve CD cover art that was for a slightly different edition of the CD.
Now I'm ripping classical CDs, and here I begin to detect that this technology is not exactly, entirely perfect. What I'm realizing (after doing exactly zero research about this) is that WMP is leveraging a wee bit of crowdsourcing in order to come up with track listings.
For example, I put in a Dvorak CD that was an old Sony reissue on the "Essential Classics" label. WMP found the CD, no problem, but this is what it came up with for a track listing:
Oops. A DGG recording by Helene Grimaud was tagged by someone who I think must have intended to come back later and finish:
This RCA recording was tagged by someone who could not be bothered to repeat all of that stuff for every movement, good golly:
And this one made me, as the kids say, LOL. This budget "White Label" brand recording was tagged by someone who had heard of Mendelssohn but not "other guy":
("Other guy" is the admittedly obscure composer D. Cimarosa.)
There have been a few — very few — classical CDs that have flummoxed ol' WMP completely; it just has no idea what the CD is or what the tracks are. I'm keeping those in a pile for the end, because I'm going to have to go in and manually enter the names of all the tracks, bleah. (For that Cimarosa CD, it's going to be 37 tracks.)
On the plus side, perhaps my manually entered labels for the mystery tracks will become part of WMP's communal knowledge about these CDs. And someone down the line will some day slide some classical CD into their computer and get the benefit of what I enter. Assuming, of course, that I do a good job. :-)
[categories]
technology
|
posted at
08:54 AM
|
trackback
|
|
link
Among his accomplishments, as people note, was that Ritchie was an excellent writer. Here's the New York Times: “There was a remarkable precision to his writing,” Mr. Kernighan said, “no extra words, elegant and spare, much like his code.” Of course, this is most evident in what might be the most famous programming book, namely The C Programming Language, which Ritchie wrote with Brian Kernighan:
The book is widely regarded as one of the best programming tutorials ever written: a complete introduction to C in 228 pages (1st edition). K&R, as it's known, is a much-beloved book, having a place in the hearts of programmers that Strunk & White does in the hearts of writers.[1] (It helps, of course, that the C language itself is sparse, but this simply underscores that Ritchie understood economy of style in more than one field.) A page on the Bell Labs site shows the many translations of K&R into languages other than English.
The style of coding that Kernighan and Ritchie used in their book became a model for how to write C programs. Likewise the writing style in K&R had wide influence on how programming books came to be written, and many a book has strived to be "the K&R of ______" for a particular programming language.
K&R is also responsible for what's surely the best-known example in programming circles, namely "Hello, World". As represented in K&R, it looks like this:
main()
{
printf("hello, world\n");
} The term "Hello, World" has entered the lexicon of programming to mean the first example for any programming language. Wikipedia includes an entry that shows "Hello, World" examples for 59 programming languages, from ActionScript to Visual Basic.[2]
In fact, "hello world" has come to mean the first or simplest example for how to start learning most anything. Some examples:
Sometimes you just have to marvel at people's achievements. Dennis Ritchie helped to write the foundational programming language of the modern era, helped launch the operating system that's the backbone of the Internet, and oh, yeah, helped define modern documentation style. How cool is that?
[categories]
writing, technology
|
|
|
|
|
