|
|
|
posted at
06:12 PM
|
trackback
|
|
link
The advantage is you can go right to your version and be assured that what you're reading applies to you. The disadvantage is that the versions pile up (4 versions and counting), with a lot of overlap, which is inefficient in various dimensions.
Are you familiar with a doc set that handles versioning differently than this? (Conceptual or API reference or both.) If so, leave a comment with a link.
Thanks!
[categories]
writing, aspnet, technology
|
Wednesday, 6 January 2010
|
Straight into the vein
posted at
10:01 AM
|
trackback
|
|
link
Email was the first electronic medium to raise my clock speed, and also my first digital distraction problem. After some "ding, you have mail," I turned off the blackberry notification buzz, added rationing to my kit bag of coping strategies, and kept on concentrating. Then RSS came along and it was like memetic crystal meth. The pursuit of novelty in super-concentrated form delivered like the office coffee service. Plus, no one had to worry about all that behind-the-counter pseudoephedrine run around. "Hey, read as much as you want, no houses were blown up in Indiana to make your brain buzz."
It was a RUSH to know all this stuff, and know it soonest; but it came like a flood. That un-read counter was HARD to keep to zero and there was always one more blog to add. Read one interesting post and be stuck with them forever. In time keeping up with my RSS reader came to be like Lucy in the chocolate factory with the conveyor belt streaming by. From my vantage point today, RSS seems quaint.
The good old days. I gave it up for good last year when I finally bought an iPhone and tapped Twitter straight into the vein. Yeah, I went real time.
Now I can get a hit at every stop light. Between previews at the movies. Waiting for the next course at a restaurant. While you are talking to me on a conference call (it's your fault, be interesting). When you look down at dinner to check yours. Last thing before I go to sleep. The moment I wake up. Sitting at a bar. Walking home. While opening presents on Christmas morning (don't judge me, you did it too). In between the sentences of this paragraph.
I am perfectly informed (I will know it before it hits the New York Times home page) and I'm utterly distracted.
-- Jim Stogdill
[categories]
technology
|
posted at
10:03 AM
|
trackback
|
|
link
 I'm thinking about this because a) I've been digitizing LPs at a steady clip, which has garnered me many gigs of .wav files[1] that I do not want to have to reconstruct; b) Jeff Atwood today recounts a bitter lesson he learned when his service provider lost a disk and took with it his archive of blog posts; and c) I had a hard-disk failure of my own last week.
Can you throw a rock and hit someone who does not regularly back up their data? Probably all you had to do was reach up and conk yourself on the noggin. Unless you've dedicated some time to a plan and unless you dedicate time to a regular routine, odds are that there is stuff on your computer that you would lose if it went kablooey in the next 60 seconds. My kids have each lost substantial collections of music when a hard disk went south, for example.
An aside ... one disaster that I am not generally prone to these days is losing a document while I'm working on it due to the computer freezing or the power going out. As I work on documents, I save compulsively (SHIFT+F12 in Word, for example) -- essentially, each time I lift my fingers off the keyboard, I just hit Save. Too often in the past I have lost hours of work on a doc simply because it was all still in memory. Not so much any more.[ 2]
Even as aware as I am of all this, and even having at times lost data that made me, you know, sad, I am still spotty about backing up. But I'm not hopeless. What it requires from me is two things:- The discipline to remind myself that the computer can crash at any time. This helps me overcome the "I'll get to it soon" mentality.
- A reasonably convenient way to actually back up. I note this because CDs and DVDs are not it for me, not when it takes an hour to burn a DVD, times however many disks it takes.
With this in mind, I have become a fan of portable storage. For work I'm currently engaged in, I use a thumbdrive that goes with me pretty much everywhere. If I'm editing book files, or spending days on a particularly gnarly spreadsheet, I have an up-to-date copy of it on the thumbdrive. And I'm pretty good about copying the documents off to the drive the actual same day that I have worked on them. (This had the added advantage of giving me access to the file(s) more-or-less at all times. Although that then introduces an issue of version control.)
For "real" backup I use portable USB hard drives. I have my music and photo collection at home, of course, and on a 500GB drive that I sling around with me in my backpack. A second such USB drive lives in my office at work. The manufacturers of these devices generally include backup software that's probably pretty sophisticated, but I don't use that. I just copy the data to the drive.
Second aside. My most recent hard-disk failure was the USB hard disk itself. I have a Hitachi Soft-Tough that proved not to be very tough at all. Portable devices are subject to their own slings and arrows of unfortunate fortune. See Joel's post (below).
This is not a backup strategy, of course. This is just a backup tactic that gives me reason not to simply fling myself off a building if the computer dies or some other disaster transpires. I would of course still have to reconstuct all the programs I use and so on, and while that's an odious task, it's doable. Trying to recover all the actual data would be well-nigh impossible.
 And -- my overall point -- this still is some sort of backup. We have oodles of computers in the house, and I'm quite sure that all of them have data on them that will result in tears and gnashing of teeth when (not if) the drives in those computers fail.
What's your story?
More reading:
[categories]
technology
|
posted at
09:52 PM
|
trackback
|
|
link
However, I do understand that good docs are an investment and that complete docs are practically impossible, even if you're paying a fleet of tech writers. As I've noted before, we have various reasons, some of them involuntary, to spend considerable effort on providing at least some docs for every last flippin' member in the .NET Framework. The count of a list of these members goes well into 6 figures.
 At various times, folks I've worked with have done analyses of some open-source docs. There is much very fine work out there, no question. A comment that comes up, tho, is that the docs for OSS tend to cover cherry-picked topics -- there is excellent documentation for interesting features, but the quantity and quality tends to fall off as the scenarios get less mainstream. This is hardly surprising -- who wants to contribute to a community by slaving away at documentation that's obscure?
The article makes various interesting points, most of which are true of any software, open or otherwise. The point of the article, of course, is that with an OSS project, there's no management team to convince that these things are true. Instead, you have to convince your community.
"I think one thing we need to explore, though, is how to make technical writing economically feasible in the open source economy."
[...]
"The problem with documentation is that it's hard for the original developer to know what to document ... We all know we need it, but we never know how to write it without being either too sparse or too verbose and covering the wrong things anyway."
[...]
[N]ewbies "cannot be expected to read the source code."
[...]
"It can be done: examples, examples, examples ... When there are too many options, parameters and commands, examples cut through the noise to the cases most people need and the usage becomes clear."
[...]
"If the docs aren't done then the software isn't done and shouldn't be released." As the article says, it's a call to arms. I'd love to hear how this is received in the community.
[categories]
writing, technology
|
posted at
08:46 AM
|
trackback
|
|
link
You can see that in the List column, there's no checkmark for paragraph formatting. This is evident if you create a list (as opposed to paragraph) style:
(Multi-level list styles do let you specify a different indentation for each list level, at least.)
If you use the automatic list features of Word ( ), or if you create a multi-level list style, you end up using a style called List Paragraph. This is technically a paragraph style, and for List Paragraph you can modify the style definition, but frustratingly, any changes you make to paragraph styling, such as indentation or spacing, appear to be ignored.
For quick-and-dirty list formatting (which probably covers most people for most situations), this isn't really a problem. At work, however, we often need to specify interlineal spacing or other paragraph-y formatting, or we need to be able to set different characteristics for different indentation levels.
What we do, and something I tell students they can do if they need this level of control, is not to create a multi-level list style. Instead, go with the approach that olde tyme Word users know -- create a paragraph style that has all the character and (especially) paragraph formatting you need, and that also has numbering or bullet formatting. This gives you complete control over the paragraph aspects of the list items.
As it happens, in Word 2007, the default template already contains paragraph styles that are designed this way -- these are called List Bullet through List Bullet 5, List Number through List Number 5, and List Continue through List Continue 5[2]:
You can see from the style definition for List Number that it's a paragraph style + numbering:
So, when you want a numbered or bulleted list, instead of clicking the bullet or numbering buttons in the toolbar, you can apply one of these paragraph + numbering styles. This works just fine:
Unless it doesn't. The classic problem is this: you change the paragraph formatting of a paragraph+numbering style. For example, you change the indentation to be .5 inches. All seems well initially -- you apply the style to a list, as usual, and it appears to work great. (Notice that the list is now indented.)
But if you try to renumber the list, things to wonky:
The paragraph to which you have applied the customized style reverts to its default paragraph formatting. This is, mmm, annoying.
The explanation appears to lie in how Word applies styles. The following diagram[3] shows the precedence rules for styles. Note that numbering styles are applied after paragraph styles.
What seems to be happening is that Word is indeed applying the (customized) paragraph style, but when it then gets to numbering (since you renumbered, after all), Word applies both the numbering and the default formatting for a numbered list, and the default numbered-list formatting overrides (overwrites) the paragraph formatting that you want.
You can fix this, it seems. What it boils down to is that in addition to specifying your custom paragraph formatting (in the example, a custom indentation), you also specify a custom numbering style:
[Show numbering formatting]
Then when you renumber a list that uses this customimzed paragraph style, the renumbering won't also reformat the paragraph in surprising ways:
I'm not sure how official a fix this is. As in, is this how it's designed? It feels hacky and it might be leveraging specific but not necessarily intentional behavior on the part of Word. But it's worked for me.
Coming soon: a video version of this whole post!
[categories]
writing, editing, technology
|
Friday, 30 October 2009
|
Documentation survey!
posted at
02:35 PM
|
trackback
|
|
link
https://www.surveymonkey.com/s.aspx?sm=qQnlYIN2D5gQH7UhLrQyuA_3d_3d
This asks some basic information, like where you get your technical information and how you go about finding it, as well as how best to get your feedback, what type of development you do, etc.
I can assure you that we look at this stuff intently, we really do. I encourage you to go through the survey. It's only 11 questions, and it will help us out.
Thanks!
[categories]
aspnet, technology, writing
|
Thursday, 24 September 2009
|
Rocket Men
posted at
10:46 AM
|
trackback
|
|
link
 Recently I've been reading Rocket Men by Craig Nelson. This is a history of the Apollo 11 moon shot, with side trips into the history of rocketry, the Cold War, and related topics. Where The Right Stuff is a kind of cultural history (of test pilots and of the unexpected sainthood of the Original Seven), Rocket Men is more about the engineering that went into the Apollo program. Although it is for a general audience, it goes into quite a bit of (interesting-to-me) technical detail about the Apollo program and the moon mission in particular.
For those inclined in that direction, there are many astounding facts and stories. A small example: when the LEM and the CM decoupled in preparation for the LEM descending to the moon, the airlock between them was not 100% evacuated. As a consequence, when the LEM disengaged, it was accelerated by the small remaining air pressure (a small puff of air, basically) and ended up going 20 feet/second faster than planned. The ultimate result was that they couldn't land where they had planned, and Armstrong basically had to hunt around for a suitable landing spot. He put down with virtually no fuel to spare.
Ok, so, as I like to do, I copied out a few of the cites that I was marking as I read. If you're with me so far, maybe you'll find these interesting also. Cites are slightly edited for length.Before the 1990s' Silicon Valley entrepreneurs with their Red Bulls, boxed pizza, and Cheetos, there were the short-sleeved-white-shirted denizens of Houston's NASA with pocket protectors, Mexican takeout, evaporating hot-plate coffee, and ashtrays choked with smoldering cigarette butts, and before them were New York and New Mexico's Manhattan Project brain trust of alpha engineers in their fedoras and soft, floppy jackets.
In so many ways, the race to the Moon would turn out to be a sequel to its predecessor's race for atomic mastery. Both were enormous projects that only a great nation, on a federal level, could afford to attempt, and achieve. Both began with Third Reich émigrés, and a shared geography. [i.e., New Mexico--ed.] And, if the first lunar landing marked the end of the Space Race and one of the beginnings of the end of the Cold War, the Manhattan Project marked both the end of World War II and the Cold War's birth. Nelson thinks that NASA and the space program get short shrift in our current thinking about our capabilities as a nation:Why is it so difficult to honor the engineering greatness of NASA? It should be seen as part of a string of American accomplishments reaching from the inventions of Bell, Carver, Morse, and Edison, to the triumphs of the Erie Canal, the St. Lawrence Seaway, the Transcontinental Railway System, the Rural Electrification Administration, and the Tennessee Valley Authority, the Hoover Dam, telecommunications satellites, the Internet, and the Global Positioning System. Such dazzling achievements, whose dynamism is a key force in American identity, are today more often than not undervalued, or just ignored by civilians. Our civilization (especially the continent-wide, U.S. variety) could not exist without the big pipes, the vast roads, the power grids, the dams, and the people-and-cargo-carrying vehicles of heroic engineering and big science. This story makes me laugh every time:The storyline [of Wernher von Braun's life] was eventually developed by Columbia Pictures into a 1960 biopic, I Aim at the Stars, which in turn inspired a famous line by the Kennedy speechwriter Mort Sahl, who quipped that during World War II, von Braun "aimed at the stars, but often hit London." Something we don't normally think about ... Nelson notes that the Command Module had about as much room as the front seat of a car.If astronauts and cosmonauts are considered particularly brave, it is not just because they were the first to travel into outer space, but also because they willingly endured what could only be described as the world’s worst camping trip—perhaps the reason why so many NASA moonwalkers were onetime Boy Scouts. To begin with, while space food technology was considered thrillingly modern in 1969, that was a view held only by those who didn’t have to eat it. ... which was followed by an unappetizing description of the mush that they ate, and then how certain ... other ... functions were accomplished. I think it was Aldrin who observed that the bravest man in the space program was the Navy frogman who had to open the hatch of the recovered capsule after three guys had been shoehorned into it for a week.
I found the following oddly chilling, trying to imagine what it might have felt like if, as was absolutely possible, Armstrong and Aldrin had been stranded on the moon[1]: Armstrong dropped from the rung to the Eagle's footpad, and then jerked himself back onto the ladder, to make sure that after their EVA [extra-vehicular activity], he and Aldrin would be able to climb back aboard their ship. He then warned Aldrin about what "a long one ... a three-footer" the small step actually was. Aldrin, meanwhile, had to remember not to lock the cabin door after exiting Eagle, since the designers had neglected including a handle on the outside.
Armstrong was practically a caricature of the laconic (if not tongue-tied) pilot-hero. He was remote even by the standards of his profession. But in addition to his famous quote ("small step for [a] man ..."), he occasionally did have some observations, even if they were a little odd:Armstrong: "The horizon seems quite close to you because the curvature is so much more pronounced than here on earth. It’s an interesting place to be. I recommend it." As I say, the book is a more technical peek at the space program, and at 350 pages (+ notes), isn't necessarily a casual read. But I found it consistently interesting, to the point that I insisted, over Sarah's pretty strenuous objections, on reading out bits of it to her. :-)
[categories]
technology, books
|
Tuesday, 15 September 2009
|
Standard by mistake
posted at
04:18 PM
|
trackback
|
|
link
The theme is mispellings that come to be accepted, like HTTP_REFERER and SHStripMneumonic, because by the time someone notes that there's an error, the name is already established.
It was good fun -- I'm hoping to be able to submit some more in the future. Naturally, I'll let you know.
[categories]
writing, technology
|
Thursday, 6 August 2009
|
BlackhawkDatabase Down
posted at
10:56 PM
|
trackback
|
|
link
My questions:- Does it matter that it's a database error? (Why?)
- What's the difference between a temporary error and the other kind?
- If the database is down, what good will it do to try again? (please)
And has been noted before, there's something unsatisfactory about clicking Okay under these circumstances. Maybe they should just change the button label to Grrrr.
[categories]
technology, writing, editing
|
posted at
01:32 AM
|
trackback
|
|
link
Haha. It is interesting, sort of, to watch their contextualization process in action. For the first little while, alls I saw were ads for blogging software. Now and again I'll see an ASP.NET ad. Other than that, it's sort of a crapshoot.
Today I saw one that made me grin, because it indicated that the Ad Sense algorithm isn't quite foolproof. Here's the ad I saw:
Now, if you know me, you probably know that I flail away at learning to play the guitar. On odd occasions I have blathered about that here. So if there's something on the blog that's about guitar, that's not an unreasonable context for displaying an ad for learning to play bass.
But I know better. You see, there are several of us Mike Popes, and if you search Google, the first Mike Pope you get is the Mike Pope who plays jazz bass.[1] Which is to say, a Mike Pope who actually knows what he's doing around string instruments.
Thus Google ad sense has gotten slightly confused. It seems to think that folks reading this blog are fans of the jazzy Mike Pope. That would flattering to me, but ... I don't think so.
Still, if you are interested in learning bass, by all means, click through the ad. Wth Ad Sense, every little bit counts. :-)
[categories]
technology
|
|
|
|
