On Writinghttp://jeff-walden.com/blog
The BlogSun, 13 May 2018 23:36:49 +0000en-UShourly1https://wordpress.org/?v=4.9.6http://jeff-walden.com/blog/wp-content/uploads/2018/02/android-chrome-192x192-150x150.pngOn Writinghttp://jeff-walden.com/blog
3232Thou, Ludditehttp://jeff-walden.com/blog/2018/05/13/thou-luddite/
http://jeff-walden.com/blog/2018/05/13/thou-luddite/#respondSun, 13 May 2018 23:32:24 +0000http://jeff-walden.com/blog/?p=52“Next time I do a play — no author!”
— (Max Bialystock to Leo Bloom in Mel Brooks’ The Producers)

Amazon is the king of self-publishing. Millions of books — literally millions — have been sent to them by everyday writers of greater or lesser ability. Amazon has (or should have, IMHO) the text of all these books entered into a vast database. Some of these books are bad, and some are very bad… but some are good. Amazon can tell which is which from sales numbers and reviews — and possibly other methods such as text, semantics, plot, and other analyses.

If I were Amazon, I’d have an artificial intelligence (AI) absorbing all that writing, and learning how to write books. Then they wouldn’t need to pay authors anymore. Just as the Google 411 calls with their accents and universe of odd words trained Google’s voice recognition system, Amazon could use the voluntarily contributed books to train their artificial writer. Amazon has already gone far down the road to eliminating the middleman — the agent and the publisher. Why not eliminate the author as well? Amazon then could respond immediately to market indications that romances or urban fantasy or thrillers or cowboy allegory were the catch of the day. That AI would absorb several hundred thousand lifetimes of technique; it could generate a fresh new novel pretty much on demand.

Google too: they recently got the legal go-ahead for Google Books to scan perhaps billions of existing works into their database. Because of copyright, Google may not be able to offer the full text of every book through Google Books (currently, unless the book is in the public domain, they tell you where to buy the book after you’ve read a sample). But — Google is already creating self-driving cars. Do you think that deducing the principles of good writing from millions of example books is beyond their technology? Watch for Google to produce novels, too.

Luddites attacked the machines that replaced them.

Of course, there still will be room for human-written books, just as today there is a market for custom hand-made shoes. Hand-made shoes are exceptionally expensive, but even so, I doubt there are more than 1000 shoemakers in all the world engaged in making hand-made shoes, and probably many fewer. And this, too, I find dispiriting: a productive author, over a lifetime, might write 50 books (Isaac Asimov wrote or edited more than 500 books, if I remember correctly, but most writers don’t come close, and a late-starting writer might only produce two or three). An AI could produce 50 books in a few hours at most, generating them in parallel. And then produce another fifty that were completely different. And another. Novels will become cheap — just like stockings did when humans stopped knitting them and machines began to do so. Even a life in literature as productive as, say, Stephen King’s or Asimov’s or Dickens’ will not pay a living wage.

And they’d be good stories, well told. That’s what’s galling. They’d be based on millions of examples — a familiarity with literature far greater than any individual writer could accumulate and internalize no matter how diligent a reader. You may argue that the tales would lack “soul” or “humanity,” but why should they, with a thousand years of written literature to draw on for inspiration? You may argue that such books would lack creativity, that they would repeat only what countless human authors had produced previously. Please refer to the book Twenty Master Plots. We can debate the actual number of master plots, but Shakespeare’s The Tempest and the movie Forbidden Planet are essentially the same story.

I fear that the human-written book will gain the same cachet as the human-knitted scarf: it will be thought quaint and charming, maybe a bit loosely put together, perhaps destined to be a family heirloom — but essentially it will be thought defective and not as well constructed as its machine-made counterpart.

Enjoy the craft.

Note: Who were the Luddites? You might call Grand-Dad a Luddite because he still uses his flip-phone and only makes calls on it, but the term goes back to the beginnings of the Industrial Revolution, where some people did not like the social changes brought about by machinery and factory.

Estimates hold that in 1810, there were 50,000 framework knitters in England earning a good living making stockings (everyone wore stockings in those days, men with knee-britches as well as women). It was a major industry. By 1820, there were effectively no framework knitters. A skilled knitter earned a schilling for producing two pairs of stockings, a rate of pay and production that put framework knitters in the new middle class; but a machine and some barely-skilled labor could produce hundreds, if not thousands of pairs for that schilling. The stockings were not as good as hand made. They were cut for the indentation at the ankle and the expansion at the calf rather than knitted to accommodate them. But they were good enough. And stockings suddenly became cheap. The new machine-knitted material was produced as a flat sheet on what was called a wide frame; stockings were cut out from that sheet and seamed, a method still used today for stockings that have seams. These out-of-work knitters and a few associated trades that prepared yarns and finished cloth allied themselves as Luddites, who smashed the machine knitting frames and cloth finishers and threatened the men who installed them. The Luddite rebellion was an early indication of the fact that machines can adapt to the change in required skill sets far faster than humans can.

]]>http://jeff-walden.com/blog/2018/05/13/thou-luddite/feed/0Non-Traditional Documentationhttp://jeff-walden.com/blog/2018/03/27/46/
http://jeff-walden.com/blog/2018/03/27/46/#respondTue, 27 Mar 2018 23:08:01 +0000http://jeff-walden.com/blog/?p=46We writers live for words. But sometimes, more words are not what you need.

I’ve been fascinated for years by non-traditional types of documentation, vehicles to convey information that are… um… not books or web pages.

Publishers Clearinghouse is known for expertise in direct mail marketing. Opening an invitation from Publishers Clearinghouse is like opening a Christmas present. There is a cover letter. A response form. Pleas from various quadrants of the subscription spectrum. Color catalogs of magazines for your delectation. Stickers for Yes, and stickers for No, that you must affix to your response form. Gold seals for discounts. The tactile and involvement factors are off the charts. They have developed solicitation to a high and emotional art.

Now, I think we can agree that documentation is not a high and emotional art. In particular, software documentation can be a soulless intellectual wasteland. At most, you may click a mouse button or press a keyboard key. There may be a video. It is not tactile and not involving, and hardly emotional — unless something breaks, when it becomes very emotional.

So, what can we do to change that, hmmm?

Poor man’s VR

This little viewer (technically, a loupe) contains the ski trail map for a Lake Tahoe resort. You peer through it to see the map. There’s a lanyard for around your neck.

A loupe containing a ski map.

Ever skied with a paper trail map? They’re great in the lodge, but when you’re on an open lift dangling fifty feet over a rock-strewn gorge with a five-knot wind blowing, and your gloves are soaked, tugging that paper trail map out of a pocket is a special kind of fun.

But this! Just yank it out by the lanyard and take a gander. It’s never soggy. It’s tied around your neck — you can’t drop it into that rock-strewn gorge. It won’t blow away. You don’t need to take a glove off and risk dropping it down into that rock-strewn gorge, either.

How can we bend this trinket to documentation?

It’s not a computer that can display a variety of images. It’s pretty much a one-trick pony. But it could hold a cheat-sheet for a complex computer program. Or imagine a loupe that you can see through. Inside, there is a map to a particularly intricate printed circuit board, all labeled. You look through the viewer to the board… and all the parts are named, and areas of the board are color-coded. Now, imagine examining that board at the top of a 500-foot radio mast…

That’s an extreme example, but in certain situations, that one trick might be enough — one eye through the loupe and the other eye on reality. And there’s branding…

Out of the Wild Blue Yonder

This is an E6B flight computer. Wikipedia explains that it’s one of the last slide rules in regular daily use in the 21st century.

E6B flight computer, in use since the 1930s.

Pilots use the E6B to calculate wind speeds, compass headings, fuel usage and other necessary butt-saving information. Yes — pilots have real computers for those tasks, but students have to learn the basics, and the E6B has been handling things very well, thank you, since 1930.

I don’t propose that you hand out E6Bs to your clients and prospects. (Unless, of course, you’re an aviation company.) It’s the idea of a rotating scale, little windows that allow you to select from among several options, and a slide that reveals the correct selection from among a set of possible results. That combination intrigues me no end.

Do I have an application in mind? Hmmm. I’ve thought of a couple, but they’ve turned out to be too complex for my simple-minded version of an E-6B — and the point of documentation is to make understanding easier, not more complex. I continue to live in hope. One fine day I will pull my trusty E6B out of its case, and the Board of Directors will gasp with the appropriateness of my solution.

A guy can dream.

It’s from the nuclear industry but it doesn’t glow in the dark

Murphy may have been an optimist, but the nuclear industry believes in being as prepared as possible. To this end, they created event cards.

Event cards do not detail the dates of the next three country club dances, but each one lists a different possible situation (event) and tells how — exactly — to deal with it. Reactors operate at the speed of light, or near enough to it. The time for figuring out what you’re going to do is long before you need to figure out what you’re going to do.

The idea of prescribing ahead of time what to do in foreseeable situations sounds to me like something that can be applied to any number of products, business units, companies, and industries. PR departments are often prepared with pre-written news releases for catastrophic events that might strike the company. How other departments may react is often left to chance.

Event cards are not only for catastrophes. System troubleshooting or even a particularly difficult-to-manage computer program might have some kind of event card set to help users identify and handle specific condition sets.

Could an event card set be implemented on a computer? Of course… but what will you do if the event you must respond to is that all the computers have stopped working?

These three solutions are all in search of the exact right problem to anoint them with the glory and success they deserve, but I suspect that there are a lot of similar solutions out there that can be repurposed in ways that solve real and valuable documentation problems.

I’m currently thinking about cafeteria placemats…

]]>http://jeff-walden.com/blog/2018/03/27/46/feed/0Would you talk to an ad on your phone?http://jeff-walden.com/blog/2018/03/05/would-you-talk-to-an-ad-on-your-phone/
http://jeff-walden.com/blog/2018/03/05/would-you-talk-to-an-ad-on-your-phone/#commentsMon, 05 Mar 2018 02:02:16 +0000http://jeff-walden.com/blog/?p=34The true art of sales revolves around building relationships. If you don’t have a good relationship, it is much, much harder to gain the attention of the prospect or close the sale — and you won’t get repeat business.

No doubt you’ve gotten the phone call from “Heather from Account Services,” who assures you that nothing is wrong with your (unnamed) credit card, but that you should speak to a salesperson anyway. This is a spam call. There is no underlying relationship (and sometimes no working return phone number, either). Millions of these calls go out daily. It’s indiscriminate.

Five years ago — oddly, on 1 April 2013 — Nuance introduced a technology that provides an interactive voice to online advertising. The idea is that you will engage in conversation with the ad much as with Siri or Alexa, presumably about the product on offer. With all respect to the company and its technology, I have not interacted with many speaking online ads recently, so perhaps the idea has been classed with those video ads that begin their audio blurb when you open the web site.

However, I wouldn’t be that quick to dismiss the idea behind the technology. I just don’t think all the pieces are in place, yet, to allow effective interactive ads. The missing piece? AI on your end as well as on the end of the advertiser.

The Introduction

Here are the critical elements of a “phone AI” to make interactive ads work.

Your phone AI keeps track of you only for you — not for an advertiser or service provider. This may presuppose private cloud software that collects your own statistics for your own use. Your phone has been collecting your likes and dislikes for months. It already has thousands of interactions with you to draw from. Only, right now, it is the service provider and a few others who get to see them. If you had your own collection, you could make it work for you.

You must have faith in your phone (or, more accurately, faith in the AI on your phone) to adequately screen any proposed conversations. Because people don’t currently own their phones for long (about two years), it will be critical for this knowledge to build up elsewhere than on the phone, so that it can carry over from device to device.

Here’s the kicker: Your phone must make the introduction. That is, the advertiser proposes; the phone disposes. I mean this seriously: your phone introduces you to the AI entity making the call based on your known preferences, and the phone asks your permission. There is a fine line here between the phone acting as your agent or as the agent of the importuning advertiser… but real estate agents (virtually all of whom technically work for the seller) have been living this role for decades.

It must be a transaction that is worth your while. It’s easy to burn up a life at the behest of others. Ads on TV and billboards may go by unremarked. They may leave behind subtle impressions, but they do not command attention. We cannot be talking here about trivialities like Heather from Account Services or the sudden bank transfer needs of a Nigerian prince. If I’m going to spend any of my (human) time interacting with your AI, you must offer me something of substance and value to pay for my time. It does not have to be your product, but it must be of value to me. This is where Heather fails. I don’t want to speak with her, let alone need to speak with her. We have no relationship. Her call is of value only to you. I want to take calls only that are of value to me — they solve a problem that I know I have, they enhance my well-being, my wealth, or save me time — and I must be able to rely on my phone AI to determine that the call would of value to me.

Think of a highly skilled office assistant, attuned to the interests of the boss, and allowing only a very select set of callers through. That’s the level of sophistication such an AI must possess. But consider the potent effectiveness of such ads…!

With both parts in place — the advertising AI and the phone AI — true relationship-building through ads can begin. And maybe then we will all willingly begin to speak with an ad.

]]>http://jeff-walden.com/blog/2018/03/05/would-you-talk-to-an-ad-on-your-phone/feed/1Creating File-to-File HTML Cross-References in Adobe InDesign Bookshttp://jeff-walden.com/blog/2018/02/23/creating-file-to-file-html-cross-references-in-adobe-indesign-books/
http://jeff-walden.com/blog/2018/02/23/creating-file-to-file-html-cross-references-in-adobe-indesign-books/#respondFri, 23 Feb 2018 19:22:57 +0000http://jeff-walden.com/blog/?p=28You can use Adobe InDesign to output cross-references in both PDF and HTML files and maintain both outputs using the same source material.

Adobe InDesign does an exceptional job of helping you create file-to-file cross-references when you prepare a book for export to PDF. InDesign also does a creditable job of automatically outputting an HTML file and a CSS, although you must do this output file-by-file, even when you’ve gathered these files together into an InDesign book.

One of the things that InDesign does not do is preserve those PDF cross-references when you output the file to HTML. Adobe states this up front. I had no illusions on this matter.

Output a .indd file that contains a cross-reference as HTML, and you’ll see HTML code that looks something like this:

That empty <a href=""> is what remains of the cross-reference bookmark, and that spanned-and-bold GetData is the text of the linked paragraph — in this case, a level-1 head that began the file that was being linked-to. It also happened to be the name of the target file.

Why Adobe could not fill the href with the filename + .html is a design decision on their part, and I won’t debate it.

But I can show you how to get around it.

It’s a Big Book

I created a substantial API document for a client, consisting of over 100 files, plus table of contents and a multi-page index. The document is loaded with “See Alsos” implemented as cross-references, each “See Also” pointing at a separate file. The guide was acceptable as a PDF, but the client wanted an HTML rendition of the same document. As is generally customary, all the HTML files would live in the same directory, and the CSS would live in a different directory at the same hierarchical level as the HTML files. I had no control over where in their server structure the client would choose to put the HTML and CSS — only the relationship of one to the other.

The issue was how to create the hyperlinked cross-references between HTML files living in the same directory — all those “See Alsos.”

InDesign Already Creates HTML Hyperlinks

After confirming that InDesign does not output cross-references as usable links and only as empty hrefs, I turned to InDesign’s Hyperlinks window.

Adobe InDesign Hyperlinks window

The window is intended as a way for you to insert a hyperlink into a PDF, and it has some restrictions on the choices in the Link To pulldown.

URL — Requires a fully qualified URL. That is, it prefixes your file name with http:// and produces an <a href= in the HTML file. This choice is meant to link to a website, not to a web page. In my case, I couldn’t dictate that each file from the book have its own URL or dictate the structure from http:// down.

File — Produces an <a href= in the HTML file that links to a file on the local machine or server. It prefixes the file name with a full pathname. (C:\users\documents, etc.).

Email — Is inappropriate to my purpose of linking one HTML file to another.

Page, Text Anchor — Both link to a .indd document, not an HTML file.

Shared Destination — While the help system states that this selection will allow you to link to any document, my experiments showed that it would link only to any .indd document.

I tested the URL output because it produced the least and most regular file prefix — just http:// rather than a full (and varying) pathname. Its output still included that pesky http://

Light Dawns Over Marblehead

There were several hundred cross-references in the whole document, but I could manually duplicate each one with a URL Hyperlink. It would be the work of a day or so, but once done, all those links would be in place.

Note: There may be a script way of duplicating the cross-references with Hyperlinks; I didn’t spend the time trying to create one. Doing this process manually also allowed me to see if there were any cases where my method wouldn’t work for me. I didn’t find any.

By good fortune, I had adopted a file naming convention for the book that began each file name with api_. Thus, each hyperlink that InDesign would create would be in the form

I could do a search-and-replace on the exported HTML files in Dreamweaver for <a href="http://api_ and replace it with <a href="api_

Doing this:

Removed the problem of InDesign’s insertion of the http://

Would not remove any http:// links that really had to be there (they would not be followed by api_)

Would let html file call html file within the same directory without a fully qualified URL

Would not dictate where in the directory structure the files had to be located.

Conditional Text

Now I had two sets of links in each document — conventional cross-references and Hyperlink references. I created two text conditions, PDF and HTML, and applied the conditions to the appropriate links.

With two document conditions, I could switch on PDF links for PDF output, and HTML links for HTML output, and I could maintain both sets of links in the same source material. I could remove the unused http:// in Dreamweaver during post-production, and the resulting HTML version of the book was hyperlinked in much the same way that the built-in cross-references created for PDFs.

TOC and Index

This client’s document is a work in progress, but it appears that the table of contents may be amenable to removing the http:// from <a href=”http://api_… but the index is a much more gnarly problem. The hrefs in the index are individual page numbers. This makes sense, because in a PDF index, it is the page numbers that are hyperlinked, not the indexed topics. I’m not sure yet whether there is any reasonable automated way to replace the page numbers with HTML bookmarks. My project may need to go without its index for now.

Stylesheet Issues

This HTML cross-reference method requires post-processing of the HTML files to remove the http://, but it also requires post-processing for stylesheet use. InDesign’s HTML output process creates a directory for each file called <filename>-web-resource. In that directory is a directory named CSS, and in the CSS directory, the export process puts a stylesheet named idGeneratedStyles.css based on the styles from your InDesign stylesheet.

All my pages use the same InDesign stylesheet definitions; but not every page uses all styles. Consequently, the idGeneratedStyles.css varies from exported file to exported file depending on which styles the file used.

After I exported the first file, I copied idGeneratedStyles.css to a CSS directory and renamed the file main.css.

In succeeding exports, I used the HTML export dialog box to tell InDesign both to generate a stylesheet from the styles used on the page and to use main.css. (In future output, I won’t need to do that; the files will just use main.css.)

I found that the export process copied the pre-existing main.css to the <filename>-web-resource folder and linked to it there rather than link to its original location. I had to make sure that I made any changes to the main.css stylesheet I was building, and not the main.css stylesheet that export had copied into the web-resources directory. I wanted one main.css file for all files to access.

As I exported each succeeding file, in the browser I could see the styles that main.css did not already include. I added those styles from idGeneratedStyles.css to main.css. Thus, main.css slowly accumulated the definitions required by each export and made them available for use in all the files. Before I left it, I modified each HTML file to point only to main.css.

In future HTML outputs, I will have to search-and-replace the link to the generated stylesheet and re-point it at main.css. There does not seem to be any good way to overcome InDesign’s practice of copying main.css into the web-resources directory. However, after working through the book file-by-file, I won’t have to go through the process of accumulating definitions in main.css (unless, for some reason, I add new definitions).

Conclusion

Admittedly, this is a work-around that requires duplicating the built-in cross-references as hyperlinks and setting up conditional text to switch between the two sets. It requires post-processing handwork once during the initial HTML output, and later (much more minimal handwork) whenever the HTML files need to be re-generated or new ones added. But the method does achieve a result that Adobe says InDesign does not do — output HTML hyperlinked cross-references to HTML files.

By building the duplicate links and conditions into the files as the files are written, and planning for the post-processing time needed to build a single CSS file, you can use InDesign to output both PDF and HTML and maintain both outputs using the same source material.

]]>http://jeff-walden.com/blog/2018/02/23/creating-file-to-file-html-cross-references-in-adobe-indesign-books/feed/0Espiration: Machine creation outside of the mindhttp://jeff-walden.com/blog/2018/02/10/espiration-creation-outside-of-the-mind/
http://jeff-walden.com/blog/2018/02/10/espiration-creation-outside-of-the-mind/#respondSat, 10 Feb 2018 22:57:10 +0000http://jeff-walden.com/blog/?p=16Inspiration means inhaling the spirit of creativity; expiration ultimately is surrendering that spirit. But what can we call computer-sourced creativity? I call it espiration (e for “out of,” as in E Pluribus Unum). I suppose you could translate espiration — badly — as “out of breath.” We’re not out of breath, yet, but the technological changes begun by the Industrial Revolution are moving along at a breathless pace.
Four great trends in technological development.

I see four great trends in technological development. They increase over time in complexity.

Automation — substitutes machinery for labor. Automation has been changing human activity for about 250 years now, starting with the Industrial Revolution and its spinning jennies, looms, and knitting machines. Anything that can be automated, will be automated.

Virtualization — substitutes algorithm for agency. Say farewell to dealing with other humans. On-line stores. On-line travel. On-line insurance. Anything rule-based that can be vended without the intercession of humans will be vended without the intercession of humans. But that’s just the simplistic start. Autonomous cars and trucks are examples of virtual drivers. Virtual factories will speed construction planning and production-line planning. Virtual worlds will allow many potential scenarios to play out before anyone commits to a strategy. You will be able to see and sense the very pulsation of the market. Will it make you a more successful trader? We’ll see.

Augmentation — provides computer-mediated abilities; humans made better by devices. Night-vision goggles and Auto-Tune are two early examples of augmentation. Night-vision goggles help you see in the dark, and Auto-Tune helps you sing on key (two abilities that many humans lack). The da Vinci Surgical System allows minimally invasive surgery at a scale and precision that surgery by even the best hand cannot equal. Prosthetics, exoskeletons, artificial hearts, and other artificial organs provide replacement for, and eventually will enhance, human abilities.

Espiration — offers computer-sourced abilities. Thought and creation outside of and independent of the human mind. I suspect that animation and music will be the first examples of machine creation, but they won’t be the last.

Computers are not by nature independently creative. They require programming by humans. To my knowledge (always faulty) computers have not yet created other computers or computer programs without the oversight of human beings. But eventually, they will. Eventually, they will create real songs with lyrics that you want to listen to, and books of stories that describe the interior thoughts and motivations of humans.

But that speculation is for another post.

]]>http://jeff-walden.com/blog/2018/02/10/espiration-creation-outside-of-the-mind/feed/0A better horsehttp://jeff-walden.com/blog/2018/02/08/hello-world/
http://jeff-walden.com/blog/2018/02/08/hello-world/#respondThu, 08 Feb 2018 00:00:00 +0000http://jeff-walden.com/blog/?p=1Henry Ford is supposed to have said, “If I’d asked people what they wanted, they’d have told me ‘a better horse.’ ” That’s the nature of innovation — and of linear extrapolation. Star Trek (the original series) featured a single computer; now we carry computers around in our pockets. Until someone thinks of it, it doesn’t exist.
]]>http://jeff-walden.com/blog/2018/02/08/hello-world/feed/0