The art of deleting

I have a talk where I encourage everyone to be clear on the data they collect and keep. I encourage people to automate deletion so they don’t have to do anything extra. In the original incarnation of the talk, I said that everyone should apply konmari principles to the data they keep, only instead of “sparking joy”, data we keep has to have a clear and immediate purpose. It has to spark respect and utility.

I like konmari for the idea of grouping all of a similar type of thing together and then sorting them together. I, er, don’t usually attribute emotions to my socks. I think it’s a little difficult to sort data based on the emotions it gives you. Data at the scale most organizations are working at is less in the range of “books you own” and more in the range of “bacteria in your body”.

When I was looking for another analogy, I thought back to my time on the Microsoft BitLocker team. I was with them as a writer for that first year, when we were still explaining the value proposition over and over again. The laptop, we would explain, was an easy loss to write off, as long as the data on it was secured. A couple thousand dollars worth of laptop left in the back of a taxi was so trivial compared to the cost of a data exposure or breach. It was difficult to change our paradigm at the time to “trust the cloud”, but that’s where we were headed. The data was on a corporate network, or a backup, or in the rudimentary beginnings of the cloud. It was ok if we never got that laptop back. We all had to change how we thought about losing things versus losing access versus losing data.

Here are some instructions for deleting your personal data, as inspired by one of my favorite poems.

One Art

BY ELIZABETH BISHOP
The art of losing isn’t hard to master;
so many things seem filled with the intent
to be lost that their loss is no disaster.

Delete reminder emails, meeting notices, any ephemeral message about an event that has passed.
Delete pictures if they’re not labeled, anything of people you don’t know or care about.
Delete the easy levels, the games you don’t play, the spreadsheets for projects that are long past.

Lose something every day. Accept the fluster
of lost door keys, the hour badly spent.
The art of losing isn’t hard to master.

The hour badly spent is hard to delete, you’ve already done it. Nevertheless,
delete games you don’t enjoy playing.
Clear your media feeds and timelines of people who don’t feed your soul.
Dig down and delete those emailed fights with your ex, or your current. That was then; this is now.

Then practice losing farther, losing faster:
places, and names, and where it was you meant
to travel. None of these will bring disaster.

The opposition to this line is “Hold fast to dreams/for if dreams die/life is a broken-winged bird/that cannot fly
Delete who it was you meant to be, all the things that make you feel guilty.
Purge the Pinterest for a wedding you did another way
Dump fitness apps that you just wince at, delete false starts and walk away.

I lost my mother’s watch. And look! my last, or
next-to-last, of three loved houses went.
The art of losing isn’t hard to master.

What are you leaving for your heirs?
When we come to clean out your house, will there be boxes of clippings?
Clean and organize your bookmarks, toss all the pointers to dead sites
Ruthlessly rid yourself of mediocre selfies and unlabeled group photos and clutter.

I lost two cities, lovely ones. And, vaster,
some realms I owned, two rivers, a continent.
I miss them, but it wasn’t a disaster.

You will lose some things you meant to keep. That is the nature of things.
You will regret some deletions, and you will worry a bit.
I’m sorry, but life is full of loss, and paper fails and disks fail and the memory of humankind is frail.
It won’t be a disaster.

—Even losing you (the joking voice, a gesture
I love) I shan’t have lied. It’s evident
the art of losing’s not too hard to master
though it may look like (Write it!) like disaster.

Practice losing, practice letting go, practice only saving things for a year, or two, or ten.

The art of losing, of forgetting, is built into us, the entropy that causes things to fall apart. Fighting our nature is sometimes noble, but less than we hope. it’s sometimes useless, but less than we think.

Nothing I write will be relevant in 5 years, 10 at best. That’s always been true. Technical writing is like that, and I have to accept that I’m etching server instructions in the sand at low tide, or lose my heart when the waves come in. Almost nothing you write, or save, or store, or archive will relevant for longer than that, either. Learn to let it go, and prepare your writing stick to scratch meaning in the beach at the next low tide.

Loss is not a disaster.

Lady Conference Speaker: Slides

Once you get a conference talk selected, you’ll want to put together the talk. There are speakers who can give entire talks without any visual aids, but most of the rest of us count on having some pictures to look at and prompt us. There are entire books written on slides – I liked Presentation Zen and Slide:ology. I can’t replicate everything all the books have to say, but I can tell you what I’ve found useful.

As you make more presentations, you’ll find your own style and voice. Be sure to watch what other speakers are doing and borrow the best of what you see. Some people do very rapid slides, and will have as many as 90 slides in a 25 minute presentation. Some people like to linger on a few key images. Some people use words, and some people avoid them entirely. You’re going to find your voice, but in the meantime, here are some things that would have helped me to know when I started out.

Tools

Slide software falls into two categories: WYSIWYG (What You See Is What You Get) or visual design, and compiled, or coded design. The first category is things like PowerPoint, Keynote, and Google Slides. The second category is more like building an HTML page, where you specify elements in Markdown or another language. These are RevealJS, RemarkJS, Deckset, GitPitch, and others.

I only use the first kind of slide software, but people who use coded design tools appreciate the reliability and customizing options of writing their own slides from scratch. My preferred tool is Google Slides because I can work across all the platforms I write on, I can easily send the link to an organizer, and I don’t have to worry about compatibility. In the last year, Google Slides fixed two major problems I had – you can now present offline, and you can use a Bluetooth presentation remote to advance your slides.

You’re going to want to get a presentation remote. They can be had for about $20, but you can get a really nice one for about $50. It depends on how much you want to invest in your speaking future. Practice using it  to understand the range and direction that you can get away with. Having a remote means that you can get out from behind the podium and it gives you something to do with at least one of your hands.

I travel with and present from an iPad, which is more convenient for me than a full-sized laptop. I got an HDMI adapter, and that is a pretty standard expectation at this point. If a conference is using something other than HDMI, they’ll probably let you know. My entire presentation kit fits in the tiny hand-size case for my presentation remote (clicker).

Standard elements

I have some elements that appear on all of my slides:

  • Twitter handle
  • Talk name
  • Conference
  • Hashtag

That may be more information than most people need, but I have a reason for all of them.

I think the Twitter handle is most important. Very few people will remember the introduction slide well enough for them to accurately quote you 20 slides later when you say something they want to talk about. Putting it on all or almost all your slides means that if a picture gets taken, people can come find you if they want more information.

The talk name also helps people identify a picture of the slide, and sometimes it helps me remember which talk I’m in, since I sometimes re-use images. It’s especially helpful for times that I have changed the name of the talk.

Including the conference name is something I do because I re-work my slides for each conference. I don’t entirely rewrite them, but I do add and subtract slides to change the audience, the time, the technology emphasis. Adding the conference name also shows the conference and the attendees that I am thinking about them specifically. I also save each presentation separately, for my records on how talks historically evolve.

The hashtag is less essential, but I like to have it available so people can use it and I can unify my talks around it.

I like to put all these elements in one place so that I can change them easily – in this example, it runs along the bottom of all the slides in this presentation.


I also have fairly extensive speaker notes for all of my presentations – not because I read them, but because it makes the slides more useful whet they are distributed without video. That’s a personal preference, but remember that everything in the speaker notes will be visible if you distribute the deck, so you may want to be careful about what you say.

Images

Don’t steal other people’s intellectual property.

Can I say it more clearly than that? Don’t use pictures without permission.

Conference talks are absolutely your intellectual property, and you’d be rightfully irritated if someone was on the conference circuit slavishly copying your talks, so don’t do it to photographers and visual artists.

Luckily, it’s actually pretty easy to be a responsible person about this when you assemble a presentation. Images come from three legitimate sources:

  • Pictures you took yourself
  • Pictures that you paid for (Getty, stock photo providers)
  • Pictures that are licensed for re-use that you handle properly

Taking your own pictures is sometimes fun, and you can do a lot of interesting things with just your camera phone. With reasonable lighting, you can get snapshots that will look OK at conference screen size.

Buying the rights to pictures is expensive, but if you work for or are representing a large organization, they may already have a license that you can use. You can also find some relatively low-cost stock photograph suppliers, but if you’re a 60-slides kind of speaker, it’s still a lot of money.

The thing I do most often is use images that are licensed for re-use, and make sure I attribute them properly, either on the slide itself or at the end of the presentation.  I mostly use the advanced Google image search. In fact, if you are in Google Slides and you say you want to insert an image and then search for it, you will get a search tuned for images that are licensed “Commercial Reuse with Modification”. Knock yourself out, just remember to attribute them properly. I have other ways to search for licensed-for-reuse images in the Resources section.

Code examples

Not all technical talks have code. I promise that’s allowed, and I have never had code in one of my talks and yet they still let me up on stage and give me a mic.

If you do use code in a talk, here are some tips you might find useful:

  • Make the font bigger. No bigger than that. Are the characters the size of your head? Maybe big enough.
  • Use syntax highlighting. It reduces cognitive load at lets people focus on what you’re trying to say.
  • If you’re talking about a particular section, make it bright and the other parts a bit greyed out. Or leave them out all together. After all, you’re not going to teach anyone to code from a stage, you’re just showing them that a thing is possible. They’ll look it up later.
  • Murphy’s Law loves a livecoder. Although some people are virtuousic typists, lots of us get clumsy when we’re nervous. Instead of livecoding, consider taking a series of screenshots and stepping through them as slides. That way the wifi is not an issue, the remote servers are not an issue, and you reduce several variables.

Videos, sound, and other weird things

It may work. From my observation, your odds are 50/50 of getting a video with sound to work with the A/V system, especially if you surprise the technician. Do you really want to unclip your mic and hold it up to your laptop speakers awkwardly? I didn’t think so.

The medium most likely to work in a presentation is an animated gif, which is nice as far as it goes, but you need to make sure it doesn’t just…run…continously….behind you, because dang, those things are hypnotic. I have made this mistake myself, but nothing is as hypnotic as the slide I saw that was just a video of a massive domino layout, with spirals and collapsing towers, and…. yeah. It was a great illustration of the point, which was about how nothing works perfectly, but then we were all watching the looping dominoes, looking for the parts where the connections failed. Great illustration, but it completely distracted the entire audience. It’s possible to set gifs to only loop once or twice, and I strongly recommend you do that for your presentations.

Other weird things that sometimes work and sometimes just make the speaker more nervous or the audience less attentive:

  • Selfies with the audience
  • Physical humor
  • Open coffee mugs, beer steins, or anything that can dump itself on your laptop
  • Asking for audience response if you haven’t prepared them.

Resources

My new favorite resource for slide templates: Slides Carnival

A good roundup of CC0 and public domain image sites: WPTavern image resources

And of course, almost everything on Wikipedia has a reuse license, and if you go to the image page, you can get different sizes and a handy little attribution slug.

Museums, such as The British Museum and libraries, such as The New York Public Library are also working very hard to digitize and publish their collections.

A large WWII cargo ship about to slide down the dock

It’s easy to find pictures you can use, such as this great launch photo of a Liberty Ship.

 To sum up

There is no one Right Way to create presentation slides. It’s very dependent on personality and topic. I once saw a great talk that had hand-drawn slides, and one that had 8-bit art. It worked for those speakers and pulled the talk together in a memorable way. But the way you do it will come to be your style, so feel free to experiment while you’re learning. Just don’t stop learning!

Remember that slides are not the whole presentation – your topic and delivery are a huge part of it, too. Provide essential information on every slide. Do your best to be ethical in your use of intellectual property. Be careful of things that may fail and fluster you on stage. Go have fun!

Screen capture of the front page of a site using folksonomy

Human Indexing

One of the consequences of cheap storage is that we have no incentive to reduce the amount of data we keep. We believe that we’re going to be able to search for whatever we want. But we are starting to exceed our human capacity to filter the returned results of our searches. Algorithms will help us some, but they are never going to be enough as long as we keep adding data at this rate. We’re going to have to use metadata to help us find anything.

Taxonomy

For centuries, we have organized data taxonomically. All living creatures have a place in the Linnean structure. I am a chordate, a mammal, a primate, a human. There are lots of library organization systems that organize books and information. For example, the Library of Congress system has categories for everything, and room left for categories of knowledge we haven’t found yet.

Taxonomy has several problems, though. For one thing, you can only sort something into one bin at a time. Constraining things into only one category means you may not think to look in the correct places and assume that the information doesn’t exist.

Taxonomy also replicates the power structures of the culture that makes the organizational, which can be problematic. For example, there was a time when the Library of Congress system categorized Native Americans as fauna of North America. It’s always going to be dangerous to underrepresented groups to encode knowledge as the domain of a dominant group. And even if it’s not dangerous, it’s othering and discouraging.

Folksonomy

The solution that has been arising lately is called folksonomy. Folksonomy is assigning tags to a piece of knowledge, based on the contributions of many individuals. You’re already using folksonomy in more places than you know. For example, Amazon recommendations uses both taxonomy and folksonomy to drive recommendations, and so does Netflix. We use it as individuals many times we are trying to describe something that we don’t know the exact name of.

The value of folksonomy is that it doesn’t depend on a top-down organizational system. Instead, it builds an understanding and description of something from many different perspectives. Like the parable of the six blind men and the elephant, the elephant may seem very different to you based on your perspective. For example, records of the Salem Witch Trials might be about early American history, or about Puritans, or about the suppression of women’s expression, or about the racism involved. The records don’t change, but their category and description does, according to who you are, what your perspective is, and what you are seeking to teach or understand.

The downside of folksonomy is that humans are sometimes terrible, and if you leave any system of public contribution completely open, people will attempt to spoil it or use their voice to dominate it. Imagine if every instance of a book that contained Christianity or a reference to communion got deluged with hundreds of tags about cannibalism. It would become difficult to find anything that was actually about cannibalism, and most people looking for documents about Christianity would find their results pushed farther down.

The other problem with folksonomy is one of standardization. If people can freely enter tags, they will enter very slight variants. Not intentionally, but it’s just extremely hard for anyone to be perfectly consistent, let alone many people. If tags vary, then they are not useful for grouping things together, because “King Arthur” and “Arthur, King of the Britons” will not be returned together, even though he is the same historical person. Conversely, “Shaun” might return you an adorable claymation sheep or a zombie-fighting slacker. You’d need to disambiguate them to get clear results.

Tag-Wrangling and Transformative Works

The organization that I have seen balance these conflicting values best is called Archive of Our Own. AO3 is a non-profit organization devoted to hosting transformational works. Transformational works are anything that takes a source text and tells a new story, or alters the text to convey a new point of view. Because US copyright law is not yet very clear about transformational works, this is also united with an academic journal and a lobbying movement to promote the idea of transformational works as a legitimate artistic expression.

Warning: Although nothing in this post is explicit, the AO3 site hosts many sexually explicit works. I do not recommend visiting the site on a monitored system or if you choose to avoid sexually explicit material.

AO3 uses a combination of taxonomy and folksonomy to make hundreds of thousands of fanfic stories available to people who are looking for them. Users can search by story title or author, or they can step through to increasingly fine categories, such as Movies->Marvel->Captain America->Winter Soldier. Stories are then further sorted on pairings, if there is a romantic element.

Screen capture of the front page of a site using folksonomy

AO3 fandom sorting page

Authors can give stories tags. These tags frequently convey authorial commentary, or appeal to a specific in-group of readers. They also function in a descriptive role. For example, a story might be tagged:

  • Odin’s A+ Parenting
  • Thor/Hulk
  • Thor/Banner
  • Loki (Marvel)
  • Thor (Marvel)
  • Hulk (Marvel)
  • LGBTQ Character
  • Humor
  • Drama
  • Curtain fic
  • Longfic

These tags are a mix of authorial description and comment (Odin’s A+ Parenting, Curtain fic), and “canonical tags”, which are standardized tags which describe specific characters or media sources (Loki (Marvel)). If you just searched on “Loki”, you would get both the Marvel version and the mythology version. “Python” returns both Monty Python and snakes.

Searching “loki python” gives you a relatively small overlap.

Tagging also includes warnings about types of content that people find distressing. Being able to select tags away means that people will never be accidentally exposed to something they work to avoid. The community has agreed on a general set of things that will either be explicitly warned for or the whole story will be assigned “Author Chose Not To Use Warning Tags”, which means there could be anything in there, take your own risks.

The canonical tags are managed by a small army of volunteers known as “tag wranglers”. These amazing humans standardize common tags and character and source tags, and also group together similar tags. For example, if you click on the tag/link “Odin’s A+ Parenting”, you’ll see a Tag Page:

The tag wranglers have collated similar and related tags and grouped them together so that reader’s searches have more chance of success. For example, I’m American, so when I am sarcastically assigning an excellent grade, I say “A+”. But British fic-readers might instead say, “Odin’s A-level parenting”. They mean the same thing, but you would have to have an EXTREMELY well-trained machine learning system to link that, or you would need humans. Tag wranglers also work to maintain and standardize warning tags.

The Art of Indexing

One of the early influences on me as a technical writer, before I knew technical writing was a thing, was reading Kurt Vonnegut’s Cat’s Cradle. Mostly, it’s a story of apocalyptic greed, but there’s a throwaway passage:

It appeared that Clair Minton, in her time, had been a professional indexer. I had never heard of such a profession before. She told me that she had put her husband through college years before with her earnings as an indexer, that the earnings had been good, and that few people could index well.

The idea of that passage stuck with me, the thought that indexing is an art worth paying for. When I became a technical writer, I was pretty junior, and ended up with the boring assignment of generating indexes. FrameMaker made this easy enough by parsing out headings to create index entries, and I even had a tool that would permute the headings for me, so I would get entries for Shaving the Cat and Cat, Shaving. But I was unsatisfied with that result, because it was just about the headings, and sometimes I was missing key concepts, so I had to go through and do manual indexing anyway.

So often, when we say indexing now, what we mean is a concordance, not an index. A concordance is a straightforward listing of all the places a word or phrase appears in a document. An index is more carefully constructed, and only points to useful instances of a phrase or word, like introductions or significant mentions. A really good index will also include words that never appear in a document.

User language is not our language

For example, if I show you this picture

Windows Blue Screen of Death

you probably identify it as the Blue Screen of Death. But until about 5 years ago, you would not find that phrase if you searched the Microsoft website. If you had the problem, you would need to search on “fatal exception”. It’s deeply unsatisfying to look for help and not find it. Even now, you won’t find a Microsoft help page about it on the first page of Google results.

If we want to serve our users, we need to meet them where they are, using the language that they use. So if they call something a spinning beach ball or a blue screen of death or whatever, use it in addition to the name that you call it.

The point of indexing something is to make your product and documentation easier for people to use. If you are not using the language that they use, you’re only writing the documentation and index for people who already work for you.

You won’t be able to imagine the names that people call your product (hopefully good). You’ll find their words in the places that they are helping each other. Stack Overflow, user groups, mailing lists, the files and reports that your own support team keeps.

Once you’ve collected all the language that people are using, you need to roll it into your index. You don’t want to identify every instance of a phrase, only the ones that actually pertain to the answers people are looking for. You want people to get the answer, not a deluge of partially relevant information.

Attach the index tags to the place with the best solutions, and also the meta tags that you want to include in the index. For example, if you have a heading called Activating your Thromdimbulator, you will want the following index tags associated with it:

  • Activate thromdimulator
  • Turn on thromdimbulator
  • Activate thingy
  • Turn on thingy

That’s the human indexing effect. There is an index entry that has zero words in common with the heading but will still be exactly what someone needs if they think of their thromdimbulator as a “thingy” that they want to “turn on”.

Human indexing is hard, because it takes time and knowledge and deep product and industry knowledge. But the reward is that even in our search-oriented, automatically-generated world, an excellent index is going to set your product apart.


This post is an expansion on a lightning talk I gave at PyConAU 2016 and Confoo Montreal 2017.

Documentation Debt

It was a good question, and a lot of people jumped in to answer it. I’ve given a talk on avoiding product design debt — That’s what #7fights is. But I haven’t given one explicitly about avoiding debt in documentation.

To understand the problem of avoiding debt, you have to understand the economy you’re working in. Many of the companies I’ve worked with over the years identify documentation as something they need to do to reduce support costs and manage the problem of training internal people. It’s not exactly glamorous. Some companies do value and invest in docs, but it’s a minority. That means that documentation is constantly underfunded, and depending on how much discipline people have about retiring old software products, it means that writers are supporting an increasingly large corpus of text. I’ve worked on projects that were literally thousands of pages long.

The debt comes down to three parts:

  • Format
  • Legacy
  • Unknown unknowns

Format

Format is whatever your tool stack is, and how the documentation is packaged and presented. If, many years ago, someone decided you were a FrameMaker shop, well, you’re probably still a FrameMaker shop, albeit one that can now output “FrameML” or DITAFrame. But the soul of the documentation, the way it is stored is in a proprietary file format that only the priestly class of technical writers can access with relatively expensive tools.

The only way to move something out of a format like that is to strip it to plain text and then re-code all the meta-text like headings and pictures. We call it a conversion project, but it’s just as much fun as changing any other codebase on the fly while trying to still deliver things. Theoretically, there are conversion tools and companies that make that less painful, but I have never seen one work properly, and I’ve been through at least 7 conversion projects. Wailing, gnashing of teeth, and a permanent repetitive stress injury were the usual style of results.

Some parts of the industry, notably Read the Docs, Corilla, Gnome/Mallard, and other open-source-y people have been trying to treat this problem by using extremely flat files, in Sphinx or Markdown. These are essentially text files with very minimal markup that can then be parsed by a variety of different engines. It’s a good theory, but it moves the locus of control from the software knowing how to wrap text and manage hyperlinks to the writer needing to know how to do so using a constrained palette of commands. Thus, the markdown technical writer needs to know their product, and the basics of technical communication, and ALSO a syntax, instead of an interface. Not really ONE syntax, but several, with nuances and subtleties between them. The writer must be a coder.

I hang out with a lot of writer/coders, but I also keep in touch with the rest of the industry, and not everyone wants to do or be that person. They want to put more of their career development into writing and understanding their product, less into the means of production.

The debt here is the very nature of everything that is around your text. The storage, the format, the numbering, the images (oh, IMAGES, the worst kind of debt), they all contribute to what you will have to pay down.

Legacy

Aside from the problem of legacy formats, you have the problem of legacy information. In 5 years, almost all of what I am writing now will be wrong or outdated. That’s just the nature of things. But if we continue to support the software, then we need to continue to support the documentation that makes the software work. This means that in an older company, you may be maintaining documentation for products that are fifteen years old. And it is maintenance. You have to update them to have the new format, new branding, whatever you change for the new documents has to be projected back to the old documents. If you move from FrameMaker to MadCap Flare, you have a conversion problem again. And it’s not like you can just ignore it and republish old PDFs – there WILL be a reason you have to get into that document to fix something.

I really recommend making your company and product name a variable that you can easily and universally replace. Just trust me on that. It will happen.

So the older your company is, the more documentation debt you have, just like with a codebase that is several layers of abstraction balanced on an OS/390 system kept in the basement.

Unknown Unknowns

The worst kind of debt is the kind that you can’t accurately predict, but when I thought about just leaving my list two items long, I realized that this third type is the kind that has gotten me in the most trouble over my career. I can predict how long it will take to convert x-many pages from one format to another, and what percentage of my time we will have to spend updating dead documents with new logos. What I can’t predict are the documentation debts that come out of left field. The merger that brings you a new set of docs and tooling and writers to integrate. The drop-everything crisis response to a serious security breach. The training that no one realized needed to be written. Those things are almost impossible to reject, and yet they can scramble a tidy documentation roadmap all to hell.

Mitigating Documentation debt

Here are my suggestions for reducing your documentation debt as much as possible. None of them will completely rescue you from the problem, but they are all things I’ve either implemented or tried to talk people into for debt reduction.

Portability

Whatever tool you pick, make sure that it exports your intellectual property in a usable format — you don’t want PDFs, you want text, or XML, or in a pinch, HTML. Have you ever had that frustrating moment when someone sends you a Photoshop file and not a PNG and you can’t open it because you don’t have freakin’ expensive Photoshop?

Yeah, don’t end up feeling like that about your documentation. You must always be able to extract something that could be reduced to text by means of a simple script. Your software can store it in a weird relational database for all you care, as long as there is an exit scenario.

Referencing

Rigidly use universal resources for common items. Your logo? There should only be one file location for that, and the software should retrieve it every time it builds the document. That way you don’t have to change it 4 places per document (my life this week), but rather change the file in one place, keep the name the same, and all your branding is refreshed, poof!

The same goes for templates, fonts, product names, and anything else that is going to be true across multiple documents or a large document.

If you’ve chosen software that is not sophisticated enough to handle universal variables and referenced images, do what you can to imitate them. Code it yourself or get some help, but never have local images of your logo scattered throughout your files. That’s just like burning money.

Lifespans

Retire documents. The same way we say, “Hey, IE 7 still technically runs and we know some of you are locked in by third-party software, but you’re out of support”, we need to give our products and our documents a lifespan. “Hey, this document is 8 years old. We are no longer updating it, but you can download the PDF and good luck to you, traveller from the past!” Probably you shouldn’t be that snarky, though. No one using super old software is happy about it, they just have constraints that we don’t in shiny new-MacbookPro-land.*

Images

Images are the most heinous form of debt. Schematics and conceptual drawings are pretty much fine, but screenshots are a personal nightmare. They’re wrong almost instantly, expensive to translate, prone to rebranding, frequently unreadable, and everyone likes to put them in because they find it reassuring to have pictures.

My suggestion is to use as few screenshots as humanly possible, and to give them names that correspond with the page name, NOT the step they appear in. If you’re lucky you’ll be able to re-use them, but numbering with any kind of sequencing is an act of madness, because there will always be insertions and deletions.

But mostly, don’t use screenshots.

If you have to, I’m excited about this idea for automating capture with Python:

Automation

Automate as much as you can. Automate production, using the same build tools as the coders. Automate screen captures if you can. If there’s anything that can be scripted or regularized, do it. This applies to the writing itself. If you can create a template that helps people give you more usable input, it’s worth a couple days of your effort. For example, you could create templates for bug reports, for user-visible changes for release notes, for change requests, for steps.

Never accept a set of typed commands as instructions if you can distribute a script instead. Fingers are fallible.

If you’re looking for inspiration on how to automate documentation and get to the part where you’re only writing the interesting juicy bits, look to API documentation, especially OpenAPI and Readme.io. They are automating away all the tedious parts of the API reference doc creation and giving us more time to write about WHY someone would want to use this call over that one. THat is the ideal of automation – not doing less work, but doing less useless work.


Very few “professional-grade” writing toolsuites work on Macs. Your writer is not any happier about this than you are, but it’s the way it works. That said, if anyone wants to torture me by getting me a Macbook Air that won’t run my software, feel free.


I hope these tips for reducing your documentation debt help you make some good arguments in your organization. I’ll keep thinking on the topic and maybe someday it will be a talk.

My Philosophy of Technical Writing

I said earlier on twitter that I like interviews because it gives me a chance to talk about my philosophy of technical writing and how I’d go about implementing it. Good friends reminded me that the ideal way to talk about one’s philosophy and implementation is while being paid a respectable hourly rate. That is very true! I have cut off interviews that I felt were exploitative.

The problem is that most business and development people don’t exactly understand what a normal technical writer does, much less a technical documentation architect with a heavy sideline in technical speaking. If I want to get a position that fits me, I have to explain to them why they need it. I don’t worry too much that I’m cannabilizing my own business because it’s so general that even my implementation details would be hard to implement without a grounding in the disciplines I used to construct them. Offering people a taste of my thinking is only going to whet their appetite.

A luscious pomegranate

Core principles

  • No one wants to be reading documentation.
  • Technology is a means to an end, not an end in itself.
  • Users experience technology differently than creators.
  • Answering questions is more valuable than comprehensive information.

Seems straightforward when I say it like that, right? But every one of those principles is something I learned the hard way, carved out for myself, watched in action. No one taught me that. Many people contributed to my thinking, but it is my synthesis that matters here.

Implementation

At the highest level, implementation is about interrogating why we write documentation at all. Could we solve it with better workflow? UI text? Detection? Scripts? Is there some way we can change the technology so that a user is not angry enough to go look up documentation?

If they are forced to look up documentation, how fast can we answer their question? We live in a world where you have been able to use natural language search for most of a decade. We need that to be true for documentation, too. “How do I configure this on Solaris?” “What’s the curl command for oAuth”? Don’t make people look for something, just…give it to them. This answer is deceptive. It sounds very simple, and implementation is a complicated blend of search, SEO, writing, and metadata. But not all beautiful things are easy.

If you can’t use something, you shouldn’t have to write about it. If you have to take the way software operates on faith, then are you really documenting it, or are you just transcribing the unverifiable claims of engineers? There are a lot of things that you can’t run, or can’t fully run, or can’t run in production, but there are lots and lots of things that you can hack through enough to test it and see whether the steps make any sense at all.

What do you call something you can’t use, can’t improve, and can’t answer questions about?

Vaporware.

A lot of my implementation philosophy comes down to not documenting vaporware. Vaporware is not the exclusive domain of hip new startups, it can happen anywhere, to the most established or productive of companies. I once started a job with a multi-billion dollar company, only to quit it 4 days later when I realized they were not clear on whether they were making an app or an API. That is not a scenario where documentation is going to help.

The projects I like best have the following features:

  • I can use it.
  • It solves a problem (I’m not great at documenting games)
  • It has very little existing documentation, so I’m starting fresh instead of retrofitting.
  • It has a deadline.

Those are personal preferences, and I almost never get all of them, but it’s nice to know what makes you happy.

Conclusion

I can tell you what I think about documentation at great length, and I can explain what makes good and bad documentation depending on who your audience is. Given enough time and consulting fees, I can tell you how to fix your documentation, or I can fix it for you, or I can create it new from first principles. My next set of goals is teaching developers to write more practical documentation, and figuring out how to teach other writers to work like this.

(Current goals: Give a keynote speech, get paid to teach a workshop)

Lady Speaker CFP Submissions

The way one becomes a Lady Speaker is by speaking. That’s pretty obvious. But how to do you get someone to give you a stage and a microphone and an audience? That’s what this post will partially cover. Specifically, how do you submit a talk proposal?

Find decent conferences

There are lots of places you can find conferences. My three main sources are the @callbackwomen twitter account, the Technically Speaking newsletter, and Papercall.io. I also hear about conferences just generally on twitter.

Conference proposals are some amount of time before the conference, it depends on a bunch of variables. For example, the CfP (Call for Proposals) for LISA 17 just went out (mid-January), and the conference is the start of November. 3-6 months is a more typical window.

In addition to finding out what conferences are soliciting speakers, you need to find out if it’s a conference you want to speak at. My criteria are:

  • Has a good Code of Conduct
  • Has not mishandled a Code of Conduct violation in the last 3 years, that I know of
  • Understands I am providing value and deserve value in return
  • Is not promoting scary values

Let’s unpack those.

Good Code of Conduct

There have been a lot of things written on Codes of Conduct, and I don’t want to rehash years of debate. I heavily favor codes of conduct that are derived from the Geek Feminism model, but almost anything will work as long as it bans specific bad behavior, does not require (but allows) legal intervention, does not make victims do confrontation, and has actionable and specific enforcement clauses. Basically, my ideal code of conduct allows someone to make a private complaint to the conference and the conference will listen to the victim about how they want it handled, but also have a plan for dealing with a known set of bad behaviors.

Did you heckle a speaker? The conference will give you a warning once, then kick you out. That sort of thing. Having a set of unacceptable actions means that you don’t get people saying “I just said she would be even hotter wearing only a lanyard! It was a compliment! How is that not “being excellent to each other?”. Almost everyone has had corporate harassment training at some point, so people do actually know what they are and aren’t allowed to do in professional settings.

Mishandling CoC violations

Before you apply to a conference, google them. See if there is any recent uproar about them having a known-predatory speaker and not doing anything, or if they made a panel on women in technology out of all men, or if people of color are warning each other away from the conference. Sometimes you will find out that a conference screwed up and then fixed it, like Nodevember did this year by disinviting a speaker. But if they screwed up and didn’t fix it or didn’t apologize, it’s probably not a safe conference, no matter what the CoC says.

Value exchange

The first year I did conference speaking, I did it on my own dime. The second year, I got paid a couple times, but nothing like what I needed to cover expenses. The third year (this year), I only applied to conferences that said they covered speaker expenses. I had sufficient videos and experience that I was not an unknown quantity, and also, I could not afford to speak the way I wanted on my own money.

I wrote about this more in Don’t ask me to work for free, a reprise. But basically, a conference’s value derives from speakers. A speaker invests extremely heavily in researching, writing, and rehearsing a talk, and then in lost work time to give it and attend the conference. Conferences shouldn’t charge a speaker to attend. If it’s at all feasible, conferences should at least cover travel and lodging. I apply to a few conferences that charge speakers, but they also heavily subsidize anyone who doesn’t have an employer. The only thing more insulting than a conference charging me for giving away my intellectual property is a conference offering me a DISCOUNT on the registration fees. That tells me they know I’m providing value, but it’s not worth THAT MUCH.

Value match

I don’t attend conferences that I think are problematic because of their values. I don’t go to Grace Hopper because they make a lot of money off women but don’t really do a lot to nurture women’s work, especially women of color. I don’t attend conferences that are about exploiting labor. I wouldn’t, for instance, attend a conference focused on defeating ad-blockers. Your values are your own, but I’ll tell you from experience that if you show up at a conference where you are already angry at the premise, the experience you have will be stressful.

Promise them something useful

I’ve been on talk selection committees, so I have a fair idea of how it goes. The first thing that happens is there is an elimination of the obviously not-useful talks. These are usually vendor-tools talks, talks that are not the right technology, or talks that are described by a single sentence and a speaker bio that says, “You know I’m awesome!”.

What I want to see is a novel idea (it doesn’t have to be brand new), that will serve my conference attendees, and let them walk away thinking something new or interesting or making a connection they wouldn’t have had otherwise. Your CfP needs to have a value-proposition. A lot of the submission forms now explicitly ask for that, which makes it easier.

I also want to know that you understand who the target audience of my conference is. If you’re submitting to a security conference, a Password-Keeper 101 talk is not going to be relevant. If you’re submitting something that seems odd in the context of the audience, you’ll need to justify it. For example, I’m a technical writer who speaks at a lot of developer/coder/devops conferences. What do I know about that? I have to explain that to even make it past the first level.

Once all the easy choices are made, the selection committee will get down to the rest of the talks — they would like to accept almost all of these, but time and space are remarkably fixed, so instead they talk about whether you have experience, whether this group of proposals covers the same idea, and if so which is the best one. They weigh the advantanges of fresh voices agains known winners, and the disadvantages of anxious speakers against same-old-same-old. And yeah, they talk about money, and whether they should select someone local or someone who has to be paid to come in. People advocate for speakers they know, or recuse themselves from deciding on speakers they know. Hopefully, someone looks at the overall balance of the speakers and tries to make sure it isn’t like this.

This list of speakers is a little worrisome

I’m not trying to shame this one conference, but hopefully conference runners are trying to find a speaker lineup that looks more like this:

© Katura Jensen 2016

Assembled @theleaddev speakers.
Photo: © Katura Jensen 2016

If you want to be a speaker at a conference, it’s going to take hard work from you to pitch, write, and deliver a talk. And it’s going to take good luck, because there are a lot more talks than slots. And it’s going to help quite a lot if the talk selection committee isn’t using some pre-established vision of what a conference speaker looks like.

Make hard choices

If you get accepted to a conference, that is SO GREAT.

When I get an acceptance email, before I write back and confirm, I double-check (or ask the first time) about what the plan is for speaker expenses and fees. Like I said, I don’t have an enterprise behind me, so I try not to donate my time for free very often.

If they can’t pay you, and you can’t afford it, you have to decline.

If you have already accepted something else in that slot, you have to decline.

If it’s across your kid’s birthday party, you better negotiate to bring home a really amazing souvenier.

Sometimes, even when everything seems like it will be great, you get hurt and have to write the conference organizer at the last minute and say you can’t come (Sorry, @seagl!)

The key is to tell the conference what is going on as soon as humanly possible. Because the thing they’re going to do is pull up the next speaker who was regretfully turned down and ask them if they can fill in. The longer you delay because you feel bad about saying no, the less time you’re giving the next person to be able to say yes.

There’s also some stuff in here about making sure you have some time to work and see your family and eat food that you make yourself, but that’s Lady Conference Speaker 301, and I’m still at 201 myself.

Deliver

I could write pages and pages on how to write and deliver a talk, but the important things are these:

  • Show up prepared and practiced
  • Respect the work of the audience and organizers
  • Stick to your time limit
  • Work the hallway track

Prepared and practiced

This is not a term paper. You can’t write it the night before. You need to have said this thing out loud in front of an audience at least twice. Once so you can figure out what you’re trying to actually say, and once for timing. I usually practice my talks 5 times for a new talk, and 1-2 times if it’s a talk I’ve given before and revised. You are commanding the attention of, say, 50 people. For a technical audience, let’s say that they are worth $50/hr. You need to respect that for this moment, this half hour, you are worth AT LEAST $1250 in attention. How much work would you have to do to feel prepared to earn $2500/hr? Do that much prep work.

Respect the work of audience and organizers

It’s hard to sit in a conference chair all day and learn things. It’s physically and mentally exhausting. Even on days I’m not speaking, when I’m through with conference sessions, my brain is full, my legs ache, and I just want to take a nap. The audience is paying attention to you, even if they are also thinking about how what you’re saying relates to their job, and worrying about their accumulating email. The audience deserves your respect.

The organizers, whew. If you’ve never organized an event with hundreds of people, I’m telling you, it’s eye-opening. There’s all this trivia to deal with, everything from making sure the t-shirts arrive, to making sure people don’t get in without badges, to taking care of speakers who are having technical problems. Someone has to make sure the catering sets up right, while simultaneously reminding everyone of the code of conduct and answering the hotel’s question about when the tables can be set up. Odds are, the organizers won’t get to hear your talk, because they won’t get to hear anyone’s talk. They’re too busy making it happen for us. Do what you can to make their lives easier by communicating with them clearly and succinctly.

Stick to your time limit

It is a jerk move to exceed your time limit. The audience needs those 5-15 minutes to get to the next talk, possibly with a bio-break on the way. The next speaker wants to get in and set up and make sure the mic is ok. The organizers are praying the schedule doesn’t go awry in one of their rooms.

I know myself well enough to know that my talks inflate when I get in front of an audience. There’s just something that happens when I have people reacting that makes me go longer. So I always time my talks to run 5 minutes short of the limit, and I assign someone to wave frantically at me at 10 and 5 minutes before the limit. Some people talk faster in front of an audience, but an audience will always forgive you for going 5 minutes short, but not 5 minutes long.

Work the hallway track

After you give a talk, a funny thing will happen. For the rest of the conference, people will recognize you. They’ll stop you in the hall and say they liked your talk. Don’t argue with them, although that is the natural instinct of many of us who were raised to be “modest” and “not brag”. Just say, “thank you” if you’re on your way to something else.

If you have time, you will make this person’s day by stopping to talk with them about your content.

  • How will it apply to your work?
  • Was there anything especially meaningful?
  • Do you wish I had included something further? I did lots of research that didn’t make it into the talk.
  • What would you want added if you could hear this again?

These questions are a combination of engaging them in talking about their reaction, and figuring out how you can do it even better the next time.

Also, when people give me compliments on my talk, I tally them up at the end of the day and email the tally to myself, because sometimes I need to open that kind of email. “22 people stopped me to compliment my talk today” has a way of kicking Imposter Syndrome in the ass.

NOTE: At no point are you required to talk to someone who is being insulting, argumentative, or creepy. Giving a talk is not the same as giving up your right to ignore people.

In conclusion

I believe in you. You are going to go out there and make us proud! And you’re going to do it by talking about things that you want to understand, or want other people to understand. I hope you can find a good mentor in your community, but if you can’t, reach out and find one online. Some conferences even offer explicit new-speaker mentoring, which is great!

Guest post: SysAdvent!

I wrote a pitch for SysAdvent and got it accepted, and then realized that it was due right in the middle of all my travel, so it’s a good thing my volunteer editor was willing to work with me on the timing.
Day 17 – Write It Down or Suffer the Consequences

This article has a lot in common with my Fear of the Bus lightning talk, but I have a little more time to flesh out the ideas and connect them. I hope you enjoy my take on how to do minimally invasive documentation for systems and not just software.

SysAdvent Logo

SysAdvent Logo

Guest Post on OpenSource.com

I was supposed to be at SeaGL this weekend for an awesome conference with the opensource world. Sadly, I fell in the garage and dislocated my shoulder, so I can’t attend. On the bright side, the post I wrote to promote my talk at the conference is available!

Four Steps to Better Documentation

In it, I talk about a few simple steps to making sure you are writing the documentation that people need, and making it as relevant and accurate as possible.

Enjoy!

The Seven Righteous Fights: Now What?

This is the conclusion to my series The Seven Righteous Fights. For an introduction, see The Seven Righteous Fights: Overview.

Hopefully I have convinced you that these fights are worth having, worth putting some of your capital and effort into. But now how do you do that?

You can’t fight alone and win. You’ll burn yourself out trying. So take the parts of this talk you find useful back to work and see where you can fit them in.

Tactics

I’ve given you some strategy, the big goals for making your products more usable, extensible, beautiful, and well-designed. Here are some tactics.

  • Write a coding style guide and follow it
  • Host brown bag lunches
  • Pair programming for best practices
  • Add tests for accessibility and usability
  • Cultivate diversity and representation on your team
  • Ask questions

Cash is King

by taxrebate.org.uk

Money is the root of all business decisions

Money is the root of all business decisions.

Companies don’t usually (ever) change their behavior because of a desire to be more ethical, inclusive, or even more efficient. They change because it makes financial sense. If there’s one thing I’ve learned about fighting the righteous fight, it’s that money is a ridiculously effective argument.

If it won’t cost much and will save a lot, that’s your lever to move the weight of the whole company’s behavior and culture.

So what do the seven righteous fights help with? Mostly making users lives better, but also making building and maintaining the product significantly cheaper.

tl;rt

This was a long set of essays, I know. You may just be reading the last one to see if I sum up. Here it is:

Don’t build in compounding technical debt that your could trivially avoid.

and

Be productively lazy.

To be productively lazy is to be lazy over the long term. It’s automating tests and teaching your kids to do chores. It’s investing a tiny bit upfront to save yourself late nights and expensive reworks.

I’m begging you. Be lazier. Teach your teams to prize efficiency over instant results. Make future-you happy, or at least less angry.


This blog post is the final installment of my Seven Fights series. You can hear me give this talk at SpringOne Platform (August 1-4) or Abstractions (August 18-20).

The Seven Righteous Fights: Accessibility

This is the seventh fight in my series The Seven Righteous Fights. For an introduction, see The Seven Righteous Fights: Overview.

We all use computers different ways. Does your software allow that?

Here are some ways you can add accessibility with relatively little effort.

Take your glasses off. Can you see any of the interaction elements on the screen? I just started wearing reading glasses this year, and I’m so surprised by how easy it is to, y’know. See things that are small or close to my face.

If you have uncorrected vision, borrow a co-worker’s glasses – gently. It’s a medical device.

Can you still see where you are supposed to be interacting with the product?

I blame Steve Jobs

Have you ever noticed that even in a Windows shop, the designers get shiny Macs with giant Retina monitors? It’s because layout and design tools are slanted to the Mac ecosystem, so it’s self-perpetuating.

The thing is, our users mostly don’t have giant Retina monitors. Or even giant Dell monitors. Or even giant hand-crushing phones. You have to assume that there are users out there who are looking at this on old, crappy monitors and old, crappy phones. We live in this wonderland of technology, but that’s not what it’s like in the rest of the world.

Have you looked at your product on a mediocre laptop? Have you looked at it on a phone? I know we all have CSS that’s supposed to reflow based on available screen size and resolution, but have you actually looked at it, yourself, not in an emulator?

8%

8% of men are red/green colorblind. That’s not even counting the ones who have rarer expressions of colorblindness. Strangely, very few of the men who are colorblind go into design or UX work.

You can tell, because software products CONTINUE to have red/yellow/green status indicators that are the same shape. Guess what? That’s hard on people who can’t tell red from green. A product I worked on recently had nine colors of little dots to indicate the crucial status of monitored items. Only on a beautiful monitor with perfect vision can I tell the difference between a little orange dot and a little red dot.

There are a bunch of online colorblindness emulators that you can use to take a look at your product.

Color Oracle

And I’d like to acknowledge my current addictive game habit, Blendoku, which has some really excellent color-blindness accomodation that just happens to help the rest of us, too. Hurrah for Universal Design!

We are judging your link text and tabbing

Descriptive links take an extra 30 seconds to write, but they keep a screen reader from returning nothing but a sea of identical links which all say “Click here for more information”. It also reassures people that they are actually going to a legitimate site if someone has taken the time to describe the destination.

Consider your navigation in a keyboard/screen reader sense. To test this, unplug your mouse and hide it in a desk drawer for a week. How’s that working out for you? As an example, I tried to tab-navigate this WordPress composition page. I’m pretty grateful I can still use a pointing device, because there are a lot of menu items, they are all at the same level, the tab order is confusing, and I’m not sure I actually got back to the composition page. 

You would be surprised by the number of people who prefer not to use a mouse, or can’t. Who have moved from mouse to trackball to trackpad and are still actively experiencing pain from trying to use a pointing device. I know of at least three senior-level technologists who are using a Wacom tab and stylus as their menu navigation device because keyboard navigation is that bad.

Fix this by setting up a reasonable tab order, allowing people to collapse long menus from the keyboard, and bringing back keystroke shortcuts.

The internet is not of uniform density

Not everyone has high-speed broadband

Not everyone has high-speed broadband

This may shock you, but not everyone has broadband, and not everyone has employer subsidies for their cell phone data, and sending people video that starts without their action is RUDE. There are lots of other reasons people don’t have infinite data or access to the internet. They may not live in a tech city in a developed country. They may not be able to afford that much data on their phone. If you require people have access to always-on data, you are shutting out a huge percentage of the world.

I worked on the Microsoft Server team for a while, and I fought and lost a righteous fight there. Lots of the Windows documentation was moving to an on-demand model which allowed us to update and tune the documentation after the software was released.

That is a pretty cool idea, but there are exceptions. The most important one is that there are lots of servers that should not be connected directly to the internet and need a firewall with pretty ferocious security rules to keep out web traffic. People who run server rooms are not excited about reading web pages from in there. Letting your server touch the internet is like letting it lick a dirty toilet seat.

But because we as a team had always-on internet and no particular firewall restrictions, none of us were feeling the problem of not having the ability to download documents on the fly, so the documents we put on the distribution were sadly minimal and server administrators had to switch to another computer to try and get the help for their problem. But the other computer wasn’t licensed as a server instance. You see the problem.

Because we had access, we assumed everyone did, and because of that, there were a lot of angry server admins who could not get to help that we had actually written.

There are also people who live in rural areas of this country who don’t have cell phone service, let alone any data fast enough to stream. There are people in other countries who are charged the equivalent of multiple days pay for data. We are, to put it mildly, not very polite about this. Maciej Cegłowski wrote a great talk/post called The Website Obesity Crisis. You should read it.

TAB: Temporarily Able-Bodied

We are all only temporarily able-bodied. Eventually, we will pass into the realm of accident, age, or disease. Some of already have and are sitting next to you in the room. We swear under our breath at grey-on-grey websites with grey buttons, or bottomless scroll that makes it impossible to get to the links at the bottom of your page with tab controls.

Aren’t they worth fighting for? Aren’t you worth fighting for?

Summary

Accessibility isn’t just about users with impaired vision, and it isn’t about Other People. Accessibility is about building something that people can use without pain or distress.


This blog post is part 7 of my Seven Fights series. You can hear me give this talk at SpringOne Platform (August 1-4) or Abstractions (August 18-20).