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 Speaker Small Talk

Sometimes, I think the hardest part of going to conferences is the unstructured time – lunches and happy hours and sponsored parties. That’s the time I remember I’m surrounded by 2,445 total strangers. And I’m supposed to be networking with them. If I think too much about this, I end up at “what do I even do with my face?”

The goal is not really “networking” in whatever negative way you’re thinking of. The goal is finding interesting people and showing them that they have neat things going on.

It turns out that conferences are full of people who are alone or nearly alone. If you came as part of a team, or you are working the conference, the social stuff is different, but if you are alone, here are some things I do.

Look odd

I have fuschia hair that I wear in a variety of short, eye-catching ways. Since I’m almost six feet tall, I’m really easy to find in a crowd. You don’t have to make quite so striking a personal style statement, but it’s useful to have people able to find you because you’re wearing a tophat, or orange sneakers, or all safety orange, or whatever it is you decide on. Your conference friends, the people you have met at other conferences, will recognize it. Strangers will see you on stage and note the thing about you so they can find you to ask questions later. And if you make it something less permanent than hair color, you can not wear it and totally blend into the crowd.

Make a friend in the registration line

Odds are, you’ll be standing here a few minutes. This is a great time to turn to the person next to you and ask them their name, and what they’re here to see, and what they’re looking forward to going to. Not, like, all at once. Then you sound like a teacher asking about a book report, but as conversational starters. Is this your first year here? If you’ve been before, is there some local food I can’t miss? For the rest of the conference, you’ll probably be able to spot that one person you met early on and give them a friendly nod. And if you’re very lucky, the name on their badge will be readable.

Sidenote: The minute I get any standard-length lanyard, I tie a knot in the back of it so that it hangs higher on my body. Now people looking for my name don’t have to track their eyes past my cleavage. This is a habit I picked up several years ago, and I think that having your name as close as is comfortable and feasible to your face is a win.

Go to other people’s talks

It’s super tempting to hide in your hotel room frantically preparing for your talk. I’ve been there. But I also know that a large part of the value exchange in this conference is that it consts money to attend and I’m not paying anything. So I try to go to a talk in as many slots as possible. I might take the slot before my talk off, and sometimes, depending on how drained I am, the slot after. But mostly I really want to go to people’s talks. It may seem odd, since I don’t have power over any servers, I code in no languages, and I only nominally work in teams, but I still get a lot of value out of conference talks. The technical ones help me keep a finger on the technology zeitgeist. The people-oriented ones always teach me something, because being a consultant is both managing up and sideways.

I always livetweet the talks I go to, but that’s for a different post. Mostly what I want out of going to other people’s talks is an understanding of a technology or application of technology, and to have attended the same conference as other people. At a multi-track conference, it’s easy to go to different conferences in the same venue, depending on your interests, but if you go to talks, you’ll always be able to ask what other people went to, what they thought, and then respond with what you learned or wanted to argue about from the talk you watched. “What talk did you get the most out of today” is a lovely, neutral question and sparks a lot of conversation.

Remember the theory of paradoxical popularity, or charismatic loneliness

I’m sure there is an actual psychological term for this, but lazy googling did not find it. Did you know that the prettiest girl in a high school gets asked on fewer dates than an average-looking girl? Did you know a lot of people that you think of as important, or influential, or famous, eat conference dinners alone? 

That may be by choice — there’s a lot of people energy involved in giving a talk and then doing the networking afterwards, so if a person wants to eat alone, let them. But I’ve noticed that people I think of as amazing sparkling wonderful stars in this context are eating alone. I think we are all valuing their time as too precious for us, and not even asking, a kind of low-level excessive politeness. I’m not saying you should ask more than once, but it’s probably ok to say, “Hey, I really admire what you’re doing, I’d like to talk about it more, do you have someone sitting with you at lunch?”

Talk to the sponsors

These people are sitting at the vendor booths, handing out swag and trying to get a badge scan off you beacuse someone is juding them on this back home. If you do want something on their table, walk up, make eye contact, and ask for it, don’t just grab. If they’re busy talking to someone, spend a minute or two listening to the pitch. You may not be a person in the market to buy things now, but it never hurts to treat the people who make conferences happen well.

The same goes for organizers. They seldom get to see the conference, because they’re making it happen. The have worked months on this, and whether they’re paid or unpaid, they are on constant alert for Something Going Wrong. It’s really stressful! So if your organizer stops and asks you how it’s going, or if you have what you need, remember to say thank you before you start in with a complaint.

Pacman

I got this one from Eric Holscher at Write the Docs. We tend to naturally form a circle when we’re standing around talking about a topic.  It takes a special kind of courage to approach a ring of backs. Instead, as you’re standing in the ring, open up space between you and a neighbor to leave room for a new person to slip in and add to the conversation. You’ll be surprised by how much difference this little bit of body language makes in making your informal conversations more interesting and varied.

Volunteer

The best way to love a conference is to be part of it. Not every conference offers this opportunity, but if you can volunteer, you should consider it. Having a set role makes it easy to interact with people. “Here’s your badge and your t-shirt. Have a great conference!”. You’ll also get to know other volunteers and organizers, as there’s almost always a backstage that attendees don’t see. This is where I have had some pretty amazing conversations over the years.

Stickers

I have a gallon bag of stickers that I carry from conference to conference. People take some, I collect some from tables and people and vendors. The stickers come with stories and then I can re-tell the stories at the next conference. Much like doing a jigsaw puzzle, sorting through a pile of stickers encourages people to stand around and have an idle conversation without feeling tense or anxious. I’m sure if everyone did it, it wouldn’t be novel, but even if you have one type of sticker, from your employer or personal brand, it’s still something to talk about and enjoy together.

On the topic of business cards

Spend money on business cards. I know it seems like an antiquity in the age of tap-contact-swaps, but there’s something about the tactile delight of a good business card that makes people comment on them and remember you. Mine are especially bright, with a plasticky finish. The back of the cards more-or-less matches the color of my hair, which serves as a good mnemonic. I get mine from Moo, which means I can have the fronts different designs — I’ve used this to put 5 or 6 witty tech writer slogans on the front, and I happen to know that people will pin them to cube walls because they’re funny, bright decoration. There is no higher state of winning than having your business hard pinned to a cube wall. In contrast, printing yourself or using a cheap printing service means you’re handing out something that feels disposable, so people do dispose of it.

If you have to hand out your company cards, that’s what you’ve got, but consider if there’s some other personal branding that would feel natural and satisfying to you. At my last conference, I gave away tiny (1/4 inch) hedgehog stickers for people to put on their badges as an indicator that they’d met me. Spontaneous fan club! Or something.

Done talking now

One of the hardest things I had to learn was how to end a conversation gracefully. I almost always start by thanking someone for their time/insight/advice. Then I say something like:

  • I’m off to the next talk! Catch you later.
  • I need to make a call.
  • I’m meeting someone in a few.
  • I’ve gotta go do a thing.

I know – a thing? But it works. 

    In summary

    If you think of conference conversations as purely utilitarian, they will be difficult and dry. Instead, think of them as a way to learn a new and interesting thing from everyone. Good luck out there!

    Wordstar 2000, the Sapir-Whorf Hypothesis, and the moulding of a young mind

    I came across this interesting article about how some people still use Wordstar as a word processor. The two main points are that Wordstar is designed to be used entirely without moving your hands off the keyboard, and that Wordstar behaves more like the act of writing a document longhand than typing or retyping something in a page-based model. It delves into some really esoteric features, but the majority of the features the author mentioned were things that I remembered fondly.

    Wordstar 2000 was my first word processor, and it was the foundation that made it easier for me to grasp semantic markup like HTML when I met it later. If you wanted to bold something, you did it without switching mental contexts, you just typed a command that would make things bold until you turned it off again. There wasn’t a mouse (the “2000” was aspirational, not descriptive). There wasn’t much of a visible menu, there was just you and the black screen and the blinking green cursor. That idea of inline formatting stayed with me.

    There’s a linguistic theory called the Sapir-Whorf hypothesis that says the way we think is influenced by our language. Our linguistic pathways make it harder or easier for us to think in a certain way. I think that’s certainly true of software that we encounter at formative stages. For me, Wordstar taught me to separate the content of my writing from the formatting of the output. Now we call that writing with semantic markup or sometimes just semantic writing (which is a deplorably broad, fuzzy phrase). My formative computing and writing happened at the same time, at the end of the typewriter era (I learned to type on a typewriter) and the dawn of the visual web. I think it gives me a distinctive quirk to the way I think of text, and writing, and all the intersections thereof.

    Sarah Mei recently posted that even if Ruby did not survive as an intact language, it would influence a generation of people who think about code, the way Smalltalk influenced the generation who started originating the ideas for Agile. I loved that idea, and it made me think of the ways that academia has to trace lines of influence and inheritance of ideas. I started out as an English lit major, and we are super into “the marxist reading of Frankenstein” and who Mary Shelley had read and would be influenced by, and so on. It’s a habit we don’t have as much in technology, I think. We tend to treat ideas we adopt and raise as if they were entirely our own, and we either deliberately or accidentally strip them of context and heritage. 
    I think about that tendency when I rewrite something, and when I leave a project. Because I do work-for-hire writing, there is almost no expectation of attribution. I come in, take whatever text there is, rework it to serve the needs that I can see or have been told of, and then move on. But in some hypothetical state where software could track all my works, I wonder if you could see the places where I learned task-based writing, where I played with and mostly-discarded DITA, where I was working from story cards or working from interfaces. Academics keep track of all the things they write for publication. I have LinkedIn because I literally have no idea who I’ve worked for without a reminder.

    The thing about the Sapir-Whorf hypothesis that I find extra fascinating is that if you really and truly learn an additional language, you can remap or add onto your thought paths, identify colors that don’t exist in the original language*, construct ideas that just don’t work in your original language, all sorts of magical thinking. Learning an entire human language is daunting, but any language we learn, any concept we internalize can rewire us to an extent. I have probably…. 8 distinct registers for writing, and each of them is deliberately learned and curated. Every time I add a new one, I can see places that it would have been handy to think this way on past assignments.

    What does all that have to do with my first word-processor? It makes me honor how different pieces of software “think”, what their paradigm is, and how I can write in a way that keeps that intact. For example, this week I learned something vital about YAML files ( I think). I was having a terrible time getting an indented TOC to work, and the error message was just this side of useless. I took a break to do some sewing, and reminded myself that the curves have to match on the sewing line, not the edge of the fabric, the edge of the fabric is not important. When I came back to the accursed YAML file, I figured out that the indentation is not based on how many spaces you are in from the line start, but that your indentation marker is directly below the first letter of its container. That changes the whole paradigm. The program is not counting spaces, it’s counting the first meaningful character on a line. If I get this into my head well enough, the next time I meet something like that, I will know to check my assumptions on which part needs to match.

    What about you? What languages have shaped how you think and work? What paradigms do you use every day?
    —————-

    * I used to think that the men I knew didn’t care enough about colors to identify them correctly, and were therefore being lazy to say “blue” for both “teal” and “cobalt”. Then I realized that a) some of them are colorblind and may not even know it b) they are discouraged from or never taught the extensive color names that are practical and useful for someone who dresses as a woman. If you tell me a sweater is plum and it shows up eggplant, I’m annoyed, because those are different colors to me, and I was planning on one of them. 

    It makes me wonder how many things I’m lazy about identifying because I don’t care or I’m socialized not to make the effort. Like, um, baseball positions or birds or knots. I can learn them if I care, but I don’t right now, so it’s all “small brown bird” and “knot around things”.

    Linguistic relativity in colors

    5 Years Behind the Mic

    5 years ago, I kicked off the conference-speaking section of my career, with this classic hit:

    So many things about this! Like, uh, I’ve dyed my hair and learned to take my lanyard off and stopped using FrameMaker and Prezi. But also, this core theory is the basis of so many of my talks now.

    1. Users are angry about reading docs
    2. Users are searching for answers
    3. Fix the common problems first

    I expected to be a little embarrassed at watching baby!speaker Heidi, but I’m really not. I’ve polished some things, improved some processes, refined some ideas, but at the core, there’s nothing to be embarassed about here.

    I thought about what 5 things I would tell that speaker, besides she’s awesome for taking this leap.

    1. Your content is conference value. Don’t feel ashamed of asking conferences to pay.
    2. When someone compliments your talk, say thank you, don’t argue. Engage them.
    3. Never apologize at the beginning of a talk.
    4. Long introductions mean you can get less content in. Tighten them up to almost nothing.
    5. You run long. Write your talks to be shorter than the window.

    In the last 5 years, I’ve gotten to three continents, dozens of cities. I’ve made so many conference friends that there is almost nowhere I speak that I don’t know at least one other person. Conference speaking is almost the entirety of my lead generation for independent consulting. It has quite literally changed my life, expanded my career, and given me a globe-spanning network.

    Results may vary — I think I got into it at an opportune time, and I now have enough of a portfolio that I’ve gotten a couple invitations instead of straight CFP applications. But I still think it’s an amazing way to expand your career, your cicle, your industry experience, your education, and your ability to take taxis in strange cities.

    Bring some value. Spend time on your talk. Go to the whole conference. Watch other speakers. Learn new things. Google jokes that everyone but you laughed at. Learn to sleep on planes. Invest in good antacids and excellent luggage. Your talks will never be perfect, but you can keep trying.

    I believe in you.

    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!

    Post on Opensource.com: How to nail a tech writer job inteview

    I was excited to write another post for opensource.com:

    How to nail a tech writer job interview

    It’s an extension of a twitter rant I went on a bit ago, about how important it is to know certain things about interviewing as a technical writer, but no one is teaching them, from what I can tell.

    • What kind of samples should you offer?
    • What is ethical to use as a sample?
    • What is a reasonable (and unreasonable) writing test?
    • How do you talk about team projects or work for hire?

    I’m already in discussions with the team about a follow-up, based on my New Sheriff In Town talk. That one will cover how to walk into a new position and figure out what to write first.

    If you’re interested in more content on interviewing, Carol Smith and I are putting the finishing touches on a workshop about all the not-code parts of a technical interview. You’ll be able to read more about that in The Recompiler soon, and of course, I’ll post about it here.

     

    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.

    New Workshop at Portland Write the Docs

    I’m excited to announce that I’m  going to be presenting a workshop associated with Write the Docs in Portland! Write the Docs is an exciting community-based conference that draws in a mixture of technical writers, support folks, independents of all stripes, API writers, open-source developers, and a wide variety of other types of people. We all come together to talk about how we can use documentation to get our point across to users, and how our experiences can help others. It’s the technical conference of my heart.

    20160524171117

    This year’s lineup looks amazing, as always, and I am assured that the snack time will once again have house-made graham crackers, so I am excited to be attending. (Seriously, the catering is delicious)

    I’m teaching a workshop on structuring and writing documentation. It says in the overview:

    This workshop is designed to teach you a few basic theories of technical documentation, such as task-based topics, reusable content, and writing for an audience. After the overview, you’ll learn techniques for writing bug reports, error messages, and onboarding instructions in a tool-agnostic, repeatable way. You’ll leave this workshop with a handful of techniques, templates, and tests that will improve your team’s communication and your life as a developer.

    What that means is that I’m going to give a crash course in the key theories of modern documentation and then guide people through some exercises that will hopefully help cement the theories. My goal is that people will leave with some tools that will help them think through their options for documentation. I know that many small companies and organizations don’t have enough money or enough work to supprt a writer, but there is still some degree of writing  that needs to be done.

    If you’re interested in attending this workshop, you can buy tickets through the Write the Docs site. If you’re interested in this workshop or a full-day workshop for your team, you can contact me. I have a special workshop I’m designing to walk a team through their onboarding procedure so they can get it out of their heads and into shareable form. Documentating and streamlining onboard is a really cost-effective way to save time for senior people.

    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.