Monday, September 30, 2019

The Ten Commandments of Code (or Doc) Reviews

I've seen several articles about how painful code reviews can be for developers, but not as many about documentation reviews. That may be because there aren't as many documentation reviews or they don't get held to the same standards. But they are similar many respects, and they can be painful for writers to endure (speaking from personal experience).

The 10 Commandments of Navigating Code Reviews could almost have been written for technical writers and documentation reviews.
The first two commandments are especially relevant:

  • Thou shall not take it personally.
  • Thou shall not marry thy code (or docs, in the case of writers).

Yes, there are some differences between the two kinds of reviews, but not as many as you might think. Most writers should find this article relevant, espeically if you work for a company that has a formal review process.

Sunday, September 29, 2019

Featured Links - September 29, 2019

Links to things that I found interesting but didn't want to do a full post about.

Friday, September 27, 2019

Sharship!

As William Gibson said: "The future is here now. It's just not evenly distributed." There seems to be a lot of it in Texas right now.

Four Reasons To Use Office Online

I came across the article,
Don’t Pay for Microsoft Word! 4 Reasons to Use Office Online Instead, recently and it prompted me to have a look at Office Online. I can't say that I was impressed.

Yes, it's free and offers some collaborative features. That might do for a simple draft of something. But there's so much missing. The first document I tried to open was password protected; the online version of Word wouldn't open it. Not only that, I couldn't get rid of the warning dialog so I had to close the tab.

Many useful features are missing, track changes, for example. No macros; for me that's a biggie. No cross references either.

The online version of Word might do for a quick letter or note, but I can't imagine using it for anything halfway complex. Even Google Docs, despite its many flaws, is better and at least offers add-ins that provide some of the missing features in the base version.

I might have to upgrade my copy of Office 2013 at some point, but I'll stick with the desktop version, thank you very much.

Thursday, September 26, 2019

Pocket Casts Has Been Updated

The other day I noticed that the Pocket Casts app on my phone had some new features; it had been updated in the background without me noticing. As it turns out, the feature update is part of a major revamp of the application.

For one thing, the mobile app (IOS or Android) is now free; it used to be $3.99. The desktop player is now $1.00 a month or $10 per year. If you paid for the desktop player in the past, it will be free.

New features include the ability to select multiple instances of a podcast at once and mark them as played, download them, or archive them. This is handy and a much needed feature if, like me, you subscribe to a lot of podcasts but there are some you listen to only occasionally.

I did have one problem after the upgrade. The app kept stopping on me. After some googling, I found a topic on their support site that described this problem and provided a solution (I had to fiddle with the battery management settings on my phone).

I've been using Pocket Casts now for about three years and it's earned a spot on my phone's home screen. There are many other podcast apps out there, but I can't think of anything that they could offer that would cause me to switch to something else.


Wednesday, September 25, 2019

How Starships Will Return From Orbit

SpaceX CEO Elon Musk has provided some details about how their Starships will return from orbit. I've been wondering about this, given that there will have to be some form of thermal protection on at least the bottom of the vehicle.
To an extent, Starship’s reentry profile is actually quite similar to NASA’s now-retired Space Shuttle, which took approximately 30 minutes to go from its reentry burn to touchdown. Per the above infographic, it looks like Starship will take approximately 20 minutes from orbit to touchdown, owing to a dramatically different approach once it reaches slower speeds. Originally described by Musk in September 2018 and again in recent weeks, Starship will essentially stall itself until its forward velocity is nearly zero, after which the giant spacecraft will fall belly-down towards the Earth, using its wings and fins to maneuver like a skydiver. The Space Shuttle landed on a runway like a (cement-encased) glider.
This unusual approach allows SpaceX to sidestep the need for huge wings, preventing Starship from wasting far more mass on aerodynamic surfaces it will rarely need. The Space Shuttle is famous for its massive, tile-covered delta wing and the leading-edge shielding that partially contributed to the Columbia disaster. However, it’s a little-known fact that the wing’s size and shape were almost entirely attributable to US Air Force demands for cross-range performance, meaning that the military wanted Shuttles to be able to travel 1000+ miles during reentry and flight. This dramatically constrained the Shuttle’s design and was never once used for its intended purpose.
We will probably find out more this weekend when Musk is scheduled to give a more detailed briefing on the Super Heavy/Starship progress. 

R. I. P., Robert Hunter

Robert Hunter, poet and lyricist for many of the Grateful Dead's most well-known songs, died Sunday evening at the age of 78. 
For the Dead, Garcia and Hunter teamed up for many of the band’s most popular compositions, like “Uncle John’s Band,” “Touch of Grey,” “Casey Jones,” “Friend of the Devil, “Truckin’,” “Franklin’s Tower,” “Eyes of the World,” “Sugaree” and “Scarlet Begonias,” among many others. Hunter also worked with Bob Dylan on multiple songs from the late-’80s onward and more recently has collaborated with songwriters like Bruce Hornsby, Steve Kimock, Jim Lauderdale and David Nelson.
Hunter received the Americana Music Association’s Lifetime Achievement Award in 2013, followed by an induction into the Songwriter’s Hall of Fame (with Garcia) in 2015.
The Relix article does not mention what may be Hunter's most beautiful lyric, to the song, Ripple. I cannot imagine a more fitting
legacy than this:
If my words did glow with the gold of sunshine
And my tunes were played on the harp unstrung,
Would you hear my voice come through the music?
Would you hold it near as it were your own?
It's a hand-me-down, the thoughts are broken,
Perhaps they're better left unsung.
I don't know, don't really care
Let there be songs to fill the air.
Ripple in still water,
When there is no pebble tossed,
Nor wind to blow.

Tuesday, September 24, 2019

How the Invention of Spreadsheet Software Unleashed Wall Street on the World

I discovered spreadsheets almost as soon as they were invented. In the early 1980s, I was working at a camera store and had to manually update a spreadsheet of daily sales using an adding machine. When I got a PC, I was able to convert that to Visicalc and could update it in seconds instead of half an hour.

Later, working at a small software company, I learned about the joys of pivot tables in SuperCalc. Pivot tables are cool tools, by the way, and I used them at the TSX to do an analysis of field names across a series of protocol specifications. (The documents contained lists of fields per messsage; I needed a list of messages by field, and pivot tables made it possible to reorganize the data in that format).

Obviously, my applications were trivial compared to the needs of big companies and Wall Street analysts. However, the more complex the application, the more likelihood of errors, either due to faults in the spreadsheet software, mistaken assumptions, or bad or missing data. And those could have real-world consequences, as this long article in Gizmodo points out.
By shifting much of the actual number work onto techno-tools, Wolfe said, financial firms have widened the gap between decision-makers and the real-world impacts their work achieves.
Regarding his colleagues who worked on The Big Short, Wolfe commented, “They really make clear that people at the top of financial institutions did not fully understand how instruments designed and used by people under them worked. They made billion-dollar bets without understanding what they were doing. They knew the upsides, but not the downsides.”
Incidentally, the so-called “junk bond king” may have argued something similar, Deringer said; in a nutshell, Milken hinted at technological determinism, a concept that lives on at big firms today.
“Apparently at one point he said that, actually, if you wanted to identify who were the real culprits for the new, freewheeling, sort of morally boundary-crossing forms of finance that developed in the ‘80s, the people to really look at were the inventors of VisiCalc,” Deringer said.

What Ad Astra Gets Wrong

On Gizmodo, astrophysicist and film critic, Andy Howell, rips into  Ad Astra, the new big budget space epic starring Brad Pitt.  (Lots of spoilers so don't read it if that bothers you.)
As an astrophysicist and a film critic, I’ve been waiting my whole life for a big-budget adventure film that spans the whole solar system. There are some stunning sequences in Ad Astra, and many of the details about astronaut life and space travel are spot-on. But some of the themes and ideas that drive the plot are based on astronomical misconceptions.
Ad Astra touts itself as having help from NASA, so presumably someone somewhere gave them some advice. Still, there are plenty of ways science advising can go wrong— miscommunication, script conflicts, misconceptions, and outright mistakes. In Ad Astra, those mistakes range from wrong ideas about space travel to inaccuracies about basic astronomy.
What bothers me more is the disregard for real science and physics. I will go to see the movie anyway, but I hate having to turn off the intellectual part of my mind when I sit down in the theatre. Why has it been 50 years and nobody has beaten 2001 at getting it right?

Monday, September 23, 2019

Personalized Concert Sound

I don't go to as many concerts as I used to - the last "rock" concert I went to was the Richard Thompson Electric Trio last December. The sound for that one was about as good as live sound gets in a smallish venue, reasonably loud and clean enough that you could hear the lyrics. But I've been to big concerts in the last couple of years (Rush and Arcade Fire), where the sound was a wall of mud.

That's where Peex comes in. Peex is a set of headphones with a microphone attachment that pick up a broadcast of the concert soundboard feed and allow you to mix it yourself with a phone app.  The built in microphone is used to determine your position in the hall and synchronize the soundboard feed with the sound reaching you. You can up the vocals, turn down the drums, or boost the bass to suit your preferences.
In my testing, the power of Peex became immediately apparent once the first lines of “Bennie and the Jets” hit. With my earbuds out, the audio sounded just as I thought it would (even in the sparkling new Chase Center in San Francisco): A mushy wall of noise reverberating in my skull, lyrics comprehensible only because I already knew what they were. But when I popped in my Peex earbuds, the experience was immediately transformed. Even before I started fiddling with the equalizer settings, I found all the instruments were tighter and scrubbed of echo, and, critically, Sir Elton’s voice rang out above them all, accompanied by his crisp strikes of piano keys.
Once you start fiddling with the equalizer settings it’s hard to stop. By “Tiny Dancer,” I had found the experience benefitted even further by pumping up vocals a few notches along with keyboards, while leaving the other instruments dialed back. As John has a whopping three percussionists on stage, comprising half the band, I quickly realized this powerful trio could be safely leveled down a touch.
Obviously this has to be done with the permission of the performer so you won''t find it available at every concert. Currently, you can try it out on Elton John's farewell tour.

This is a genius idea and I hope I get a chance to try it out sometime.

Dazzle Camouflague and Disruptive Patterns

Until a couple of years ago, I always had the mental picture of World War I battleships as sleek and grey, like their WW II counterparts. But that's not the case, at least not in the latter part of the war. They were painted in what's known as dazzle camouflage with the hope that it would make it harder for enemy gunners to get a correct range on them.


The wonderful Pulp Librarian on Twitter has a long thread about dazzle camouflage and how it was used in WWI. Unfortunately for photographers everywhere, the advent of radar made it unnecessary and it wasn't used in WW II or later.

Dazzle camouflague is part of a larger field known as disruptive colouration or disruptive patterns. I've recently seen articles about it being used to confuse facial recognition systems and to fool the AI vision systems used in self-driving vehicles.

Sunday, September 22, 2019

Featured Links - September 22, 2019

Links to things that I found interesting but didn't want to do a full post about.

Saturday, September 21, 2019

Margaret Atwood's The Testaments On the BBC

BBC Radio 4 is serializing Margaret Atwood's The Testaments, the sequel to her hugely successful and influential novel, The Handmaid's Tale. So far, five episodes are available with two episodes being broadcast each weekday until October 4.

Each episode is about 15 minutes long and will be available for a month after the broadcast date. BBC Radio 4 is available world-wide on the Internet and is free to listen to.


Friday, September 20, 2019

What It Takes To Weigh a Neutrino

You've probably heard of neutrinos–tiny, almost massless particles that can zip through the entire Earth without striking anything. They're not quite massless though, and that's led physicists to go to incredible lengths to weigh them.

The photo below shows part of the experiment that scientists used recently to nail down the neutrino's mass

An experiment nearly two decades in the making has finally unveiled its measurements of the mass of the universe’s most abundant matter particle: the neutrino.
The neutrino could be the weirdest subatomic particle; though abundant, it requires some of the most sensitive detectors to observe. Scientists have been working for decades to figure out whether neutrinos have mass and if so, what that mass is. The Karlsruhe Tritium Neutrino (KATRIN) experiment in Germany has now revealed its first result constraining the maximum limit of that mass. The work has implications for our understanding of the entire cosmos, since these particles formed shortly after the Big Bang and helped shape the way structure formed in the early universe.
The mass turns out to be no more than 1.1 electron volts. Compare that to an electron, which has a mass of about 500,000 eV.

You can read more about the KATRIN experiment on Wikipedia.

Thursday, September 19, 2019

A Space Elevator We Could Build Now

The idea of a space elevator that could carry payloads into orbit without a rocket has been around for quite a while. But the materials strong and light enough to make it practical don't exist yet.

However, there's now a design for a space elevator that uses materials that exist now and could be built with current technology. What makes it possible is that it would be anchored on the moon and go to geosynchronous orbit.
The researchers’ main result is to show that today’s strongest materials—carbon polymers like Zylon—could comfortably support a cable stretching from the moon to geosynchronous orbit. They go on to suggest that a proof-of-principle device made from a cable about the thickness of a pencil lead could be dangled from the moon at a cost measured in billions of dollars.
That’s clearly ambitious but by no means excessive for modern space missions. “By extending a line, anchored on the moon, to deep within Earth’s gravity well, we can construct a stable, traversable cable allowing free movement from the vicinity of Earth to the Moon’s surface,” say Penoyre and Sandford.
The savings would be huge. “It would reduce the fuel needed to reach the surface of the moon to a third of the current value,” they say.
While this is technically feasible, I question whether it makes economic sense. But it would be a heck of a trip, if a long one (at 1,600 km./hr. it would take almost 10 days). 

Don't Qut Your Day Job

A recent article published on Medium has been causing a bit of a stir in the small section of the Twitterverse that I follow. It's written by Heather Demetrios, a successful novelist. Her first books netted her $375,000 in advances, and she thought that she'd hit the big time and started living the life. But sales weren't that great and her next advances got smaller and smaller. Reality bit, big time.

The article offers some solid advice for writers, some of which is applicable to the more mundane writer types who are sitting in cube farms working from contract to contract.

I'm going to add a link to the response by Elizabeth Bear, who is a successful (and very good) author of science fiction and fantasy. Her latest novel, Ancestral Nights, was published earlier this year to generally favourable reviews. Again, while the article is aimed at novelists, some of her points will be applicable to freelance contractors.
  • Pay off your debts when you can, buy durable goods that last when you need them (rather than the cheapest available) and stick to a budget.
  • Don’t spend ludicrous amounts of money on self-promotion and travel. Build your brand and your network by treating people well, making friends, and providing interesting internet content. By all means go to literary festivals, cons, and so forth if you’re invited or if you want to go for the social opportunities, but if going to cons made you a best seller I would not be sweating how to pay the mortgage now.
  • Be aware that the money is going to come at weird times and it will get held up when totally inconvenient, and sometimes you’re going to have to chase people down who have been sitting on an invoice for months. Sometimes years.
All of this makes me wonder how many writing programs, be they creative writing or technical writing, offer a course on the business aspects of the career?



Wednesday, September 18, 2019

Blocking Calendar Invitation Spam

Spammers, being inventive sorts, have found a way to get spam to you by using calendar invitations. I haven't had any (yet) myself, but from what I've read, it's become a more common problem.

Fortunately, it's easy to block. Follow the instructions in this article from Krebs on Security, which explains what settings you need to change in calendar applications from Google, Microsoft, and Outlook. There may be a downside, however:
Making these changes will mean that any events your email provider previously added to your calendar automatically by scanning your inbox for certain types of messages from common events — such as making hotel, dining, plane or train reservations, or paying recurring bills — may no longer be added for you. Spammy calendar invitations may still show up via email; in the event they do, make sure to mark the missives as spam.

The Training Commission

The Training Commission is a near future science fiction story by Brendan Byrne and Ingrid Burrington, published as a series of emails. You can read it online at the link above.
Several years after a period of civil unrest and digital blackouts in the United States, a truth and reconciliation process has led to a major restructuring of the federal government, major tech companies, and the criminal justice system.
In this still-rebuilding America, freelance journalist Aoife Tkachenko is just trying to make a living (and a name for herself outside of the shadow of her famously-martyred older brother) when she stumbles onto a document from the commission’s archives that many powerful people would rather keep buried. As she digs deeper into the story (all the while dispatching her findings to her newsletter subscribers), Aoife realizes that what she’s found could upend America’s tenuously held peace–and get her killed in the process.
It's quite brilliant featuring excellent characterization and world building coupled with a page turning plot. I am fairly certain that it will be a top contender for next year's Hugo and Nebula awards.

Tuesday, September 17, 2019

Excel Caused Errors in Genetics Research

I have been bitten more than once by Word auto-correcting my text into something I didn't intend. And we have all seen the (sometimes hilarious) results of phone auto-correct run wild. But I didn't know that auto-correct in Excel could be dangerous, until now.

It turns out that many genetics researches have errors in their data because Excel converted common gene names to date format.
The spreadsheet software Microsoft Excel, when used with default settings, is known to convert gene names to dates and floating-point numbers. A programmatic scan of leading genomics journals reveals that approximately one-fifth of papers with supplementary Excel gene lists contain erroneous gene name conversions.
The problem of Excel software (Microsoft Corp., Redmond, WA, USA) inadvertently converting gene symbols to dates and floating-point numbers was originally described in 2004 [1]. For example, gene symbols such as SEPT2 (Septin 2) and MARCH1 [Membrane-Associated Ring Finger (C3HC4) 1, E3 Ubiquitin Protein Ligase] are converted by default to ‘2-Sep’ and ‘1-Mar’, respectively. Furthermore, RIKEN identifiers were described to be automatically converted to floating point numbers (i.e. from accession ‘2310009E13’ to ‘2.31E+13’). Since that report, we have uncovered further instances where gene symbols were converted to dates in supplementary data of recently published papers (e.g. ‘SEPT2’ converted to ‘2006/09/02’). This suggests that gene name errors continue to be a problem in supplementary files accompanying articles. Inadvertent gene symbol conversion is problematic because these supplementary files are an important resource in the genomics community that are frequently reused. Our aim here is to raise awareness of the problem.

A Beginner's Guide to Git

The first project I worked on in my first full-time technical writing job was a manual for IBM's CMVC (Configuration Managment and Version Control). I had no experience at all with the subject and it was a heavy slog. Since then, I have had to use several different version control systems, up to the current favourite, Git.

Free Code Camp has just published a beginner's guide to Git. Since many (if not, most) developers use Git now, some knowledge of how it works is a good thing for technical writers to have. You may even be asked to put your documentation into a Git archive.

This article covers the basics and is a good introduction to version control concepts.