Retrograde tooling

We've reached a tipping point in technical writing, and we need to deal with it.

The future is not going to involve producing documents, it's going to be producing seamlessly integrated content in and around products, and that means we need to change our expectations around tooling. This is going to hurt, but hopefully in the good way.

When I started writing, I learned FrameMaker. It was amazing. It had 20 years of history even at that point, and you could do anything with it. Equations, printer's crop marks, swapping text blocks in and out automatically, producing print, PDF, and help files from the same file, complete with changing cross-references. Using Frame was as much art and science, and there were key commands that were transmitted through the mailing list, by word of mouth, because they were no longer in the official documentation. It had a learning curve like a brick wall, but once you got through it, you were driving an unstoppable tank that could roll over any problem.

After 15 years, including occasional painful exposures to trying to do professional documentation in Microsoft Word, we got a new, hot product called MadCap Flare. It was like FrameMaker had been reincarnated for the web. It was easier to use, had integrations for localization, CSS, HTML5. It was shiny and beautiful and powerful. I could still do conditional text, referenced text blocks, and single-sourcing.

I haven't used a technical writing tool like that in 18 months, and I think it will happen less and less often.

The rise of Software as a Service and app culture is driving us away from a world of User Guides and Admin Guides and Installation Guides. Instead of CDs with instructions, we expect pop-up help bubbles and interfaces that guide us through what we should be doing. This makes a lot of sense, since we are all experiencing individualized experiences based on our bandwidth, app collisions, needs, and licensing structures. Writing a document that includes all that would be extremely difficult with the old tools, and we don't have the old tools anymore.

We don't have them because without the need to produce Official Documentation, we've reduced and eliminated technical writing departments and jobs. We're moving a lot of that work into User Experience, and we are asking the writers that remain to serve as a clearinghouse for content produced by developers. Instead of a journalism model, where we interviewed developers or were embedded on the team, we are now working as aggregators, taking content from many sources and getting it ready to distribute. Or there just isn't a writer, and publishing is much more ad hoc.

FrameMaker and Madcap Flare cost between $1000 and $2000 per seat license. That's not something you're going to buy for someone who is doing it part time. And it's hard to port data in and out of them, because of all the metatext and compiled information that's attached to them in the tools. It's a database, not a set of flat files. Or more accurately, it's a compiled binary – not the program, the document. So a writer using one of these tools would be a hard gating function on a team's ability to publish their own writing. It would look great, but you'd have a single point of failure.

Instead, we've been moving toward having technical writers use tools that are freely accessible to developers. Markdown that is compiled with readthedocs or readme.io or some other blunt-force tool to create a page with a table of contents and some minimal linking. The advantage of this is that everyone can read, write, and access the docs. The downside, which is mostly only visible to technical writers, is that we have lost enormous richness in treating our documentation as an object-oriented compiled object.

Here are some examples of things that I either can't do or are very difficult:

  • Conditional text – different output text based on flags set on the whole document.
  • White-labeling – configuring my documents so secondary organizations could brand them themselves
  • Smart localization – Doing bulk localization based on common words and phrases, reducing translation time and cost
  • Write once/publish many – having a master document that can produce help, web pages, print, and in-product assistance
  • Context-sensitive help tied to the page the user is on
  • Tables – Markdown, why are you so bad at this?
  • Sophisticated layouts – headers, footers, breadcrumbs, inset images and text blocks
  • Automatic ingestion and formatting of other file formats
  • Includes, referenced text, inserted files – think libraries

That's a lot to lose! Sometimes I feel like writing in Markdown is like making Gutenberg to give up on the printing press and presenting him with and angry goose and a curly sheepskin.

However, it's not going to do me any good to bemoan the lost glories of the tech writing tools Roman Age, because we are in the Dark Ages now, and we just have to move forward to the Enlightenment as soon as we can.

….I was going to make a comparison table for you here in WordPress, but that's not a thing. My point exactly.

Anyway, here's what I think we could start using to regain some of our lost abilities:
CSS – Might be able to help with layouts, HTML5 support, tables, and white-labeling
Feature flags – conditional text, write once/publish many, and ingestion
HTML – (stop laughing. HTML is much more fully featured than Markdown) tables, context-sensitive help, includes
De-duplication – smart localization, includes
Javascript, PHP, etc – ingestion and formatting, menuing, navigation, breadcrumbs

Wow, that's a lot to learn. On the other hand, I heard a talk last week that included a 5 minute list of everything you "needed" to know to become a useful devops engineer, so I guess it's not bad compared to that. It is a pretty intimidating list for people who got into technical writing because they like writing, rather than because they like technology. It's not that writers can't learn tech – obviously we can, because we learned those old tools. It's that there is only the beginning of a community around this new renaissance writing, and no one tool that we can teach juniors.

I fell into tech writing because I took an English literature class with a very avant-garde professor who taught us hand-coded HTML (because 1995). That was the key that opened the door for me. But what key is out there now?

I hope Corilla continues to learn and grow and thrive – they could add in many of these features or already have them.

I hope Read the Docs gets enough funding to hire someone who is a technical writer as well as a coder, because they are missing some significant use cases, but they are also an industry standard.

I hope the OpenAPI standard and Swagger make it more possible and easier to expand their powerful use of code snippets into non-API documentation, because they are coming at the problem a new way and it involves a lot of the hypertextuality I'm looking for.

I hope Confluence realizes that they are setting people up to create unusable wikis because they default to an older, siloed world.

And honestly, I hope SharePoint spontaneously combusts, because that is TERRIBLE.

New employment: LaunchDarkly

Last week I told you about my exciting new job title, Developer Advocate.

This week, let me tell you about my exciting new employer! On Monday I started a job with LaunchDarkly, a startup that does feature flags as a service.

Feature flags are a way to distribute software with reduced risk. For example, if you had a holiday-themed CSS page that you wanted to activate after Thanksgiving, but you didn’t want the risk of deploying something that might break your holiday shopping experience, you could wrap the CSS in a feature flag. Using the feature flag, you can decide when to turn on the stylesheet. You can set the percentage of people who see the stylesheet. You can even hit the emergency kill switch for the stylesheet if it does cause problems.

Feature flags can also be used to test new features for part of your audience, or to replace conditional text, or to control which customers can access premium or paid features.

There are a bunch of implications that spin off from the ability to turn features on and off quickly and reliably – it changes some core thinking about what deployment is, how we think about a product, and what we do when something goes wrong. I’m really especially looking forward to working with customers to make sure that we are using and respecting their use cases. For example, while I was at DevOpsDays, I ran into someone who asked me how LaunchDarkly worked with HIPPA standards. I get to either find or write a white paper that gives them coverage for their needs.

It’s exciting to be an an inflection point in how we think about things. It’s happened to me a couple times — full disk encryption, multi-cloud management. I think this one may be another one. Ask me about it!

Why on earth would developers WANT to write documentation?

This week I was at DevOpsDays Minneapolis, which was an amazing, warm, and inclusive event. There were at least three open spaces on documentation, communication, and related problems, and I didn’t propose any of them!

Minneapolis DevOpsDays 2017 logo

The question the devops world keeps asking, over and over again is,

How do I get developers to write anything?

There aren’t a lot of easy answers for this.

The first one is that if you care about developer-produced documentation, you should hire for it. But almost always, the people hiring are not the same as the people feeling the pain of missing documentation, so that may not happen.

The second is that you should hire someone other than the developers to write, if that’s important to you. I’m going to mention that all the times I’ve interviewed at Google, it was to be as an internal systems writer, documenting how things in the company work for other people in the company. Big, smart, companies hire writers for internal documents. But that is a tough budgetary sell.

The third, partial, answer, is that you make it significantly easier for developers to write. You give them forms and templates to fill in instead of expecting them to invent documentation theory. You specifically allocate writing time that can’t be budged for “one more tweak to the feature”.

Here’s the key problem though:

No developer has ever been fired for lack of documentation.

No developer I know of has gotten a bonus for documentation.

There is no stick. There is no carrot. There are a lot of competing demands on a developer’s time. Why on earth would they go do something that is not in their core competency just because you want it?

My instinctive response, whenever my kids want something, is to say, “It’s good to want things.” I think that is the instinctive response of most developers who are asked to do extra work. It’s not malicious, it’s just true. There is no reason they should do it – they won’t lose their jobs, the way they might if they prioritized writing over code. They won’t derive any benefit except the long-term and intangible one of being asked fewer questions. If they like being the source of knowledge, they’d be giving that away. If they like coding, you’re asking them to do something other than what they want. There is no upside.

So knowing that, how can we encourage developers to write documentation that we need?

First, reward it. Give people prizes for writing docs, or for throwing away or revising old docs. This needs to be something outside their usual compensation structure. Gift cards, time off, merit badges, whatever would be meaningful to that person. Ask them. They know what rewards them, because they use it to reward themselves.

A variety of rewards

Second, require it. I don’t mean “You have to write some docs or I will, uh, be disappointed in you.” I mean “The presence of documentation is a quality gate and you cannot release without it.” I mean “QA is using your docs as the test story.”.

Companies are never altruistic, humans are never purely motivated. We need to accept this and stop expecting people to do extra work because it’s the right thing to do, and start making the work not-extra, and the reward tangible.

New job title: Developer Advocate

I've had a lot of job titles in my career:

  • Technical Writing Intern
  • Queen of Documentation (It was 2000, OK?)
  • Technical Writer I, II, III
  • Technical Communicator
  • Senior Technical Writer
  • Technical Writing Consultant
  • Documentation Architect
  • Documentation Mercenary

You might notice a theme there. I've been a technical writer for a lot of different companies, because that's been my career, my expertise, and my passion. I want to take everything that's great about technology and make it easier to use, more transparent, more thoughtful, more humane.

Lately, I've been having trouble describing what I am doing in terms of writing alone. Two job interviews in a row, my interviewer stopped asking me questions about my qualifications so they could take notes on my ideas for their product. My conference talks are sort of nominally about writing, but actually about patterns I'm noticing in the world and in technology. I love writing, and I'm never going to give it up, but it's also…not quite a good fit anymore.

Through the power of All-Women-In-Tech-Are-Connected, I got an interview for a Developer Advocate position. I would never have applied for this position on my own – it's so far beyond what I think of as my skill set. But in the discussions and interviews, I really came to believe it was not just a company I could work for happily, and a product that I think is useful and not toxic, but a position that lets me get out there and do the kind of thinking and helping and problem-solving that I love.

Photo credit: Women of Color in Tech Chat

Developer Advocate is a super broad range of positions, actually, but our interpretation of it is basically me continuing to do all the things I'm doing now: conference speaking, blogging, listening, and noticing. It's just that now I'll be doing all that and getting paid for it, instead of using it as a loss leader for my consulting. I get to go out in the world, find out where developers and users need help, and figure out how to make it happen for them. We're seriously at "pinch me, I must be dreaming" levels of exciting here. I even get to keep writing a little, although I may have reached my personal career goal: not writing the release notes.

Yes, I'm being deliberately coy about my new employer. That deserves its own post. I'll just say that I think we're going to get along well, they say I get to continue to be a pink-haired weirdo, and I will feel proud of the product.

I honestly feel like changing my job title is like the day you get new shoes and you realize you'd outgrown the old ones without noticing.

Oh! This is so comfy.

Consulting retropsective

I’ve been doing Agile for too many years to feel like I’ve learned something unless I identify it with a proper retrospective. I’m about to start an FTE job, and my consulting will obviously drop way off (but not entirely). So here we go:

What went well

  • I passionately loved the independence. I could fire a client when I thought they were doing something that was stupid/unethical. I didn’t have to account to anyone for my time at conferences. I made it to all the weird middle-of-the-day school stuff. My spouse was in the hospital for 11 days, and I could absorb that without talking about it.
  • It really forced me to get better at negotiation, scoping, planning, and self-management. No one was going to save me by telling me the priorities of projects — that was on me.
  • I learned a lot about building a personal and professional reputation. It matters that I blog. It’s important to follow up on business cards and connections. I never advertised my services except by telling people they were available, and I had stages where I turned away work.
  • I discovered moxie as a selling point. Not unreasonable bragging, but people are happier when they spend a lot of money on someone who seems confident about themselves and what needs to happen. I would have guessed that would be a turn-off, but no, that mostly applies to earlier stages in a career.
  • I got to work on some kick-ass projects and refine what parts of writing and projects I’m good at.
  • I got to go to so many conferences and learn so much stuff about things that I never would have thought I cared about, but it all feeds into the hopper and then a week or a month or six months later, it turns out that data was valuable.

A smattering of the stickers I carry around with me

What needed improvement

  • Cashflow. Sweet fancy moses, cashflow. This year to date, I have pulled in about $30k and gone $10k into debt. I had two contracts die on me after I had turned down other work to take them, and a client that paid Net-45….ish. If I reminded them. As a sole earner for a family of four, including two teenagers, this is not super. If I knew I was going to make that persistently, I would adjust our style of living, but I kept optimistically thinking that the universe would not screw me over again, right? And this was just a little bump. It wasn’t.
  • Relatedly: taxes. I did not get that set up as soon as I should have and I will spend some time untangling it.
  • I needed some things in my contracts that weren’t there: a kill fee/clause. A late fee. I racked up about $700 in late/overdraft fees because I thought people were going to pay me when they said they were. This is not a malicious problem, it’s a problem because I had already exhausted my buffer cash.
  • I need to keep working on how I track time. There is a lot of my job that is basically talking to people, wandering around thinking, and staring at the ceiling. It’s legit work, but I feel weird charging people for ‘I mowed my lawn and also thought about your data structure problem for two hours’.
  • I need to figure out how to pay myself for loss-leader/reputation building stuff, like blogging and mentoring. If I classify it as “not-work”, it eats the leisure time I need to recharge, interact with my family, and sew nifty dresses. If I classify it as work, then it’s unpaid work, which has a lot of emotional stuff going on.
Empty wallet in male hands. Isolated on white. Studio shot.

Empty wallet

Action items

If I do consulting full-time again, here are some things that make it more likely to work out for me.

  • Start with 6 months of cash buffer instead of 3. This is because I don’t have any other income stream
  • Write my own contract (well, hire a lawyer to do it), and make sure my clauses about kill fees, late fees, and payment schedule get into whatever contract I sign.
  • Hire a tax accountant sooner rather than later.
  • Work on adding passive income to smooth out bumps.
  • Factor in equipment costs and less-obvious travel costs in my calculations (if you take 50 flights a year, you wear out luggage, even the nice stuff) (I’m using a 3-year old laptop, and software costs money.)
Purple spinner suitcase

My next suitcase – a slightly smaller TravelPro in PURPLE

Software and pink collars

Yesterday, I said this:

And I want to come back and address it in a bit more depth, because someone called it “a bold statement”, and it is, but not unfounded.

Premises

Before I start, I’m just going to say up front that here are my premises, and if you disagree, feel free to go do your own research.

  1. When women become a majority in a job category, the pay and prestige of the category declines.
  2. Coders are paid more than non-coders of the same experience level at the same company.
  3. Money is a useful proxy for what a company values.

Economics

Code schools and bootcamps are frequently aimed at career-changers and non-traditional students. There is also a healthy representation of young people. Almost all of them are not putting themselves through this for some idealized love of coding, but because they want a well-compensated job.

If user experience, quality assurance, technical support, project management, or technical writing were compensated at the same rate as coding, market pressures would encourage people to offer programs that would provide the same level of education in these other fields.

All those positions are an important part of the product – they affect how people feel about using the product, how much they can accomplish, how frequent releases are. However, this is where we follow the money trail further.

The people who buy software are often not the people who use the software. The purchasers are trying to solve organizational problems while balancing budgets, ROI, security, data conversion, all that stuff. They are not the people at the pointy end of the software stick. They don’t spend hours every day entering tickets in it, or trying to port it to the cloud, or designing marketing materials, or designing microchips.

This disconnection between the user and the purchaser leads to a lot of problems where it is the best interest of the software to address the wants and needs of the purchaser, rather than the user. This complicated relationship is made even more complicated by second-order purchasers, also known as investors. Investors want to be impressed, and also want to make purchasers impressed. It’s a lot of levels of abstraction from the woman in your doctor’s office trying to enter billing data. (I fly out of Minneapolis, which is the hub link for Madison. SO MANY Epicor people.)

Investors are often like pre-Moneyball baseball. They are using pattern-matching to try to figure out which resources and people will be valuable. Enormous and important companies are driven by coders – think Facebook and Google – so it must be that coders are the most important part of a company to invest in. That seems like a successful pattern to match. I think, or at least hope, that as the market matures, we’ll start looking at how often companies make it on base with good products, not just how much they look like other companies.

Products are more than code

Good companies hire experienced people to take care of all the parts of the product that aren’t code. Great companies compensate equivalent experience equally. There are not a lot of great companies in the world.

One of my Twitter interlocutors said that it was just hard to make a value argument for documentation or usability, that people don’t understand why it matters. As a consulting technical writer, I have this argument approximately a millionty times a year. Why wouldn’t usability, consistency, and reliability matter? Do you really, actually have a functional product if only elite nerds can figure out how to install and run it? Or do you have a bunch of aspirational code that may or may not run on most browsers?

I don’t know how to solve this problem. I am doing my bit, going to coding conferences and talking to developers about what it means to write, and what mistakes they commonly make that have to be fixed by other people. The problem is much much bigger than that, though. One pink-haired speaker is not enough to change how an industry regards itself.

I blame the patriarchy

Well, really, I blame the kyriarchy, but that’s a different essay. When I say that technical writing, especially at the end-user level, is a pink-collar job, I mean that it is dominated by women. I don’t have good stats on other product jobs, such as QA, PM, and UX, but the gender ratio for them is certainly closer to even than it is in coding. I think it’s not an accident that the jobs which require more emotional labor are filled with people who have been trained to do it for more years (that’s women and under-indexed people). Pink-collar is a corallary to white- and blue-collar jobs, and conveys class as well as payment expectations.

Have you ever heard someone say, “Well, she’s a real jerk to work with, but she’s such a great writer that we just can’t get rid of her?” I haven’t. And yet I go to interviews frequently where someone asks me, “How do you work with developers who don’t like talking to writers?”.

Until we level out our status structures, we’ll keep having this problem. and well-meaning people perpetuate it. Girls Who Code. Girl Develop IT. Google Summer of Code. All the technology mentorships and programs funnel people into development, not the allied skills, because the allied skills are…lower status? Less aspirational? Most of our problem is that “the pipeline is leaky and full of acid”, but perhaps some small part of it is that we are trying to fit everyone into the square, high-status hole labeled “developer”, and some people are pegs better shaped for writer or QA.

What can you do?

  • Compensate everyone based on experience and value, not role
  • Advocate for more mentors and assistance for non-coding roles
  • Spend money on continuing education for everyone
  • Promote cross-training
  • Be aware when you are treating coders as more valuable than other team members
  • Respect everyone on their team for their contribution
BIG CONCEPTS small docs. User documentation is a failure of user interface. Faster and cheaper than making your developer write it. Elegant writing saves money. Paid by the anti-word.

Why are there no documentation bootcamps or schools?

Sarah Mei and Sarah Fox and some other people and I were talking on Twitter about code school graduates, and how they frequently do really well at mid-level positions because they have communication skills from their previous careers.

We all agree that teaching someone to write well enough to be a Professional Technical Writer is more than you could cover in a six-week intensive, probably. Depending on where they start. I could absolutely turn a motivated journalist into an entry-level tech writer in 6 weeks. They’re 3/4 of the way there already. But most people would need to learn the following from scratch (in no particular order):

  • Audience analysis
  • Task-based writing
  • Procedural writing
  • User story writing
  • Error writing
  • Bug writing
  • Conceptual writing
  • Diagrams, illustrations, and screen captures
  • Rudimentary tools use
  • Sentence construction
  • Bullet point use
  • Theory of simplified English
  • Accepting editorial feedback
  • Accepting technical feedback
  • Elements of information architecture and presentation
  • Elements of usability and accessibility
  • Style guide use

Even if you’re coming out of a liberal arts/literary background, half of that list is something you may never have heard of. You can construct a great sentence, and you know how to use a semicolon, but your experience to date has rewarded you for things that don’t matter at all in technical writing. You’ve gotten good grades for making persuasive arguments or writing pithy literature reviews, but no one in my English Lit classes ever told me that I was addressing the wrong audience or designing my headings badly.

So that’s a daunting list of things to try to cram to get people into what is, let’s face it, a less glamorous profession than Code Warrior. I happen to think it’s the best and most influential place to be in a development team, but that’s not what the pay scales say.

That said

That said, I think I could do a LOT with teaching code school students and other developers some really basic writing skills. I tried this out at a Workshop at Write the Docs this year, and it went pretty well. I’d love to present it elsewhere. I’m putting the outline below the cut, if you’re interested.

Give me your developers for a day, and I’ll teach them to write a well-constructed error code and a readable bug report and a coherent status email. Give me two days and I’ll teach them about audience and analytics and deletion.

I want to do this for code schools, so we can catch people when they are frantically learning, so they will remember to look it up later. I want to do this for open source projects, because it is so hard to find or hire a technical writer. I want to do this for conferences where junior developers are looking to elevate their game. I have been traveling around to developer conferences for several years now, trying to distill everything I know from 20 years of my career into something that has value for coders, and I am convinced it has value.

Continue reading

Open Source Citizenship Award

I was at Open Source Bridge this week, with my kiddo Baz. We were both giving talks, and I was giving a workshop on interviewing with Carol Smith. Also I got to MC the slideshow karaoke part of the after-party, which was huge fun.

But the big news is that I won an award for Open Source Citizenship. This was not captured in pictures, but I literally spun in a circle, trying to figure out who behind me was also named Heidi. They were pretty clear they meant me.

Open Source Citizenship Award

Shiny 3-D printed medal that says “Open Source Bridge Truly Outstanding Open Source Citizen 2017”

I have real trouble thinking of myself as an open source contributor – sure, I go to a bunch of open source conferences, and I write for opensource.com, and I give talks about how to be a better self-documenting writer, and I livetweet almost everything I go to, but I don’t code, you know.

It’s like that moment when you recognize your internalize misogyny. Oh, I am devaluing my contributions for NO GOOD REASON. I have imposter syndrome not about my talent (goodness knows, I’m pretty cocky about that), but my place in the community. Any minute now they’ll find out that I haven’t edited Wikipedia in 9 years, and they’ll reject me! That’s not how it goes. Contributions of all types are valuable, and I’m glad to be recognized for what I do.

In 2009 or so, there was a giant fannish explosion we now colloquially call Racefail. One of the most valuable people/roles in the whole thing was “Archivist of the Revolution” – a position held by @ryda_wong and others. They read, collated, and commented on an incredible amount of data, packaging but not altering it so that we could consume relevant posts without seeking them out ourselves.

I don’t see myself as that dedicated to the cause, but it’s something I can aspire to — to offer up information, to curate what I see, to help create indexes and pointers. I do live-tweeting because I think it’s valuable and because it’s a way for me to manage my ADD. 8 hours a day of extremely thought-provoking talks is HARD.

For a little while, I thought that perhaps I was outshining other contributors because my conference persona is loud and tweety and charismatic. And I truly feel that charisma is not always the best indicator of value to a community. There are a lot of charming assholes in the world. I hope I’m not one of them, but I assume that charming assholes never notice it until someone calls them out on it.

But then I remembered that this is voted on by attendees. Individual people found what I was doing useful. And I remembered the very smart thing that my mom told me about compliments.

“Just say thank you. Arguing is insulting their judgement.”

So thank you! I’m going to be happy that I won something! It’s true: I do spend time, money, and energy on the open source community.

  • I mentor other writers
  • I spend hours and days crafting talks
  • I quietly support other women and under-represented people, dozens of hours a year
  • I contribute thousands of words to the corpus of knowledge with tweeting and blogging
  • I ask stupid questions so other people don’t have to

That’s a pretty good list. I’m happy with it. So thank you, members of the Open Source Bridge community. I appreciate your recognition, and I’m honored.

Creative destruction

I was making a joke about the fact that I accidentally have two profiles for Open Source Bridge – one is with pink hair, and one with brown hair. Obviously, one of them is the mirror universe me. Probably the one with brown hair. No one with pink hair could be sinister, right?


I said that my mirror universe self would obviously specialize in creative destruction, instead of speed-building documentation sets from nothing. But in truth, I do both.

Any sufficiently complicated documentation set is indistinguishable from a pile of cruft.

Creative destruction is related to deleting, but is not the same. Creative destruction is less trashing things by category, and more like letting a herd of goats loose to clear a hillside covered in Himalayan blackberry. The goats are a lot more discriminating and not as destructive as a flamethrower, but they are omnivorous enough that your wild roses may also get eaten with your blackberry brambles. Creative destruction lets you take a cleared space and plant something new in it, without having to work around what has grown up over time.

This is the part of the konmari method that I identified with most. Put everything of a category together, look at it, and decide what it is that you want to keep. It's really difficult to make distributed decisions because it requires holding all the objects of that type in working memory, and our working memory, as literate humans, is just not that good. Play to your strengths, which in this case means "make it easier to be bold about deletion/destruction".

When I walk into an organization with existing documentation, I like to do a gap analysis: What traditional docs sections might they be missing? What things do I wish I knew as someone new to the product? Does the documentation cover every step of the product, from pre-installation to removal? Can people make good business decisions based on these documents?

A documentation destructionist looks to see what we can carefully, mindfully burn to the ground. Is it old? Is it about something we don't support? Is it a path we didn't follow? Archive it, delete it, and move on. You don't want to leave old versions of anything around if it will confuse the issue when someone is trying to use your tool.

Clearing a swath of ground makes it possible to see the daylight between the trees, give your good docs a bit of breathing space, plant new things that you want for the future or the present. New ideas grow best with some sunshine and elbow room, and even if you have infinite storage space for documentation, no one has infinite attention to read or maintain it.

Happy Tuesday! What can you destroy today? What would your documentation set be better without? What is out there bothering you ever time you go past it? Go get rid of it!