Docs Deserve More Respect | Hacker News Reader

Docs Deserve More Respect

ramijames.com

104 pointsramijames71 comments

The most useful part of writing docs for me is that they shine a spotlight the sharp edges of your product. Why is this feature so hard to document? Oh, because it sucks! Let's make it better, and then the docs will make sense too.

At work I sometimes frame discussions about new features in terms of how I'd describe using this new feature to different users of our product. If it isn't straightforward given the context then it probably isn't a well-developed idea, yet.

One notable example--we (a payroll platform product team) needed a better way for users to fix mistakes in checks they'd already committed to the system. We have a non-negotiable stance that says we don't edit transactions. We can add new ones to cancel out the old ones, but we don't edit stuff that's already happened. This gets really confusing to users when they're trying to change a $200 to a $50 and need to commit a -$150 transaction someplace (and then also adjust all the other things downstream from that, like deductions/taxes/etc).

So we built the "time machine". Using this feature, users can type in the $50 and let the system figure out what transactions need to be added. There's a lot of complexity in the phrase "let the system figure out" but that's sort of the point. Now our tutorial on making payroll adjustments literally says "1. Find the check you want to adjust, 2. Click 'Adjust', 3. Type in the new number and 4. Click 'Finish'".

Amazon does this a lot in their “customer obsession” management strategy. In their terms, the mechanism to make this happen is called a “PR/FAQ”[1], and the core idea is that if you can’t express your idea in terms of a customer-focused press release, then it isn’t a good thing to add.

[1]: https://productstrategy.co/working-backwards-the-amazon-prfa...

This is actually another key concept that I've been mulling how to write about. There is a direct path from docs to support and into your product cycle. The information that flows through there should be critical to informing how your next feature set you develop is selected. Obvious, painful rough edges should be fixed.

> Our habit of trying to document bugs and limitations visibly was enormously useful to the system. As we put out each edition, the presence of these sections shamed us into fixing innumerable things rather than exhibiting them in public. I remember clearly adding or editing many of these sections, then saying to myself "I can't write this," and fixing the code instead.

~ Dennis Ritchie, on the BUGS section of UNIX Manuals

I would make a -$200 transaction whose breakdown with deductions and taxes and whatnot are all mirror images of the original $200. It exactly cancels the incorrect original transaction to zero across all accounts in the ledger. This is followed by the $50 is a new, independent transaction. No brainer to understand, or audit.

That's what supermarkets do. They void transactions (usually needing a supervisor's approval) and then re-enter the purchase correctly.

In some situations this is ok. But if money actually changed hands then you can’t pretend you didn’t pay someone, so you’ve got to essentially create a debt or a new check, depending on whether the new total is negative or not. And that means all those new amounts may now need a different effective date. And each state can have different rules about collecting overpayments back from employees (some simply don’t allow it). We deal with staffing companies where folks forget to fill out Friday or fat-finger something on their timesheet, and we get it 2-4 pay cycles late, mixed in with other corrections and adjustments. There’s quite a lot of specialized logic involved.

I would say that all the additional complications make it even more imperative not to conflate the cancellation with the correction (another source of complexity into the mix), but do a clean cancel (as much as possible) followed by a reissue.

If there is any problem with the $200 cancellation, that has no effect on the correctness of the $50 reissue, which is entirely independent. It's easier to reason about problems with the $200 cancelation. Ideally, all affected accounts should be reimbursed as if the original never happened. If some account is debited $12.34 and then later credited $12.34, that's easy to match up and verify.

Obviously that’s the ideal situation. But in cases where you’ve already deposited funds you can’t pretend you didn’t.

I'm saying: do exactly what you would with the $150 offset, but use $200 to make it a complete offset. I don't see how it helps to work with $150 than $200.

> The most useful part of writing docs for me is that they shine a spotlight the sharp edges of your product.

I love this. I have written docs for dev tools companies and one section I love to write is the limitations section, especially if I am new to the product. This is helpful in so many ways.

* It lets me as a writer understand the built in limitations.

* It helps the team building the product get on the same page about areas to improve (or areas that are explicitly limited for business purposes)

* It helps with credibility for devs, as they can immediately determine if there a limitation that isa deal breaker.

The hard part is keeping it up to date, but that's true of most docs.

This is true. I have often encountered design deficiencies, while documenting my work.

> Why is this feature so hard to document? Oh, because it sucks! Let's make it better, and then the docs will make sense too.

I'm no UI/UX expert. But in writing documentation, I can clearly see messed-up UI stuff in general, and broken or incompletely implemented UI concepts in particular, and I can communicate these problems to the SW people, and get buy-in AND a proposed fix before I even file an issue.

I find it incredibly useful to do this with code too!

If you’re managing a service/library that other humans integrate with, write some fake integration code as if you are one of those other humans. I don’t mean end-to-end tests, this is even dumber than that, and must be done _way_ before codifying behavior with tests coverage to avoid future regression.

Is the integration clunky, or worse, are some interactions not even possible? This exercise will shine a sobering light on such sharp edges. Would one small interface change eliminate 30 lines of frequently duplicated integration code? Is required functionality missing?

It is difficult to surface all such usability issues in a vacuum, but they surface very naturally when actually using the tool that you are building— even if it’s all made up so far. Remember, this is for people to _use_, not a piece of art to be observed but never touched.

Put into metaphor: don’t build the world’s fastest car and omit the steering wheel, gas and break pedals, seats, doors, windows, mirrors, etc., all because you never stopped to think about how someone might _drive_ the damn thing.

I'm a documentation zealot. My eng teams understand we treat docs as products; they are project deliverables, and we allocate time to ensure we produce and maintain concise, clear and unambiguous content about the services we operate.

Nonetheless, I always have those team members who insist it's not their responsibility. A recent exchange I had with one of our engineers:

  Eng: I can create our entire service portfolio, but I just don't know how to explain it in a document.

  Me: I see. How about we start small, and just simply explain how service 'A' works. It's not too complicated.

  Eng: Well, I don't know what outline to use. I don't know how to publish it. I don't know what content I should add. I don't know who would read it. This will take too long. It feels like busy work.

  Me: So, if you're unable (seems like it) or unwilling (hopefully not) to do this work, what would you suggest we do to ensure we inform the rest of the company about service 'A'?

  Eng: I don't know.

  Me: Until we DO know, service 'A' will not be deployed.

So (based on their questions and your non-answer) you're not telling them the format, the audience, the goal of the document or how it will be consumed? And wondering why they're pushing back?

edit: And instead of answering their very reasonable and pertinent questions you instead accuse them of being either incompetent or lazy.

This is why companies are starting to replace more middle manager roles with ICs

I'm struggling to understand how somebody can be responsible for creating a service but not understand who the audience is for reading its documentation. Some of the questions may be reasonable (one would hope if documentation is a requirement there's at least a standard format, etc.) but "it feels like busy work" and "this will take too long" destroy the premise that this is about not having answers to reasonable questions.

How do you know how long something is going to take if you don't know the format, etc.? Calling something "busy work" is sort of signal that this isn't "I need help getting started" it's "I'm trying to weasel out of this."

>I'm struggling to understand how somebody can be responsible for creating a service but not understand who the audience is for reading its documentation.

Documentation can be read by product managers, managers, QA engineers, engineers on call, engineers integrating with the service, and engineers taking future ownership of the service. Which group(s) it is depends on company dynamics, culture and processes. Documentation written for the PM of another team may be nearly useless for someone on call trying to triage a bug. Documentation lifecycle also matters since otherwise you will just get useless stale and inaccurate docs. However if it's a product manager focused documentation then you may have no choice however if it's engineer focused you may want to bake most of it into code (swagger, etc.). Just document it is how you get the 99% of documentation that is never read by anyone in the future.

I read it the exact opposite, that the engineer is just being difficult, especially with the last three: "I don't know who would read it. This will take too long. It feels like busy work."

I mean, who do you think is going to read it? Obviously anyone who needs to interoperate with the service.

And the first three parts, let's address in turn:

"Well, I don't know what outline to use." Whatever outline other documentation at the company uses.

"I don't know how to publish it." So ask somebody who has published documentation how they do that.

"I don't know what content I should add." Look at pre-existing documentation and use that as a model.

I mean, this isn't rocket science here. This is clearly somebody obstructing things -- somebody who doesn't want to be a team player.

If, as an engineer, you can figure out how to set up git to make a commit, you can figure out how to publish documentation. It's entirely inappropriate to be using up your manager's time asking them to hand-hold you through this, when you can just ask a fellow team member to send you the resources you need.

This isn't elementary school -- it's a professional work environment where you've been hired for your expertise and your ability and initiative to solve basic daily problems on your own. The dialog as presented does portray the engineer as either lazy or incompetent, no question about it.

"I want you to figure out how to document things to my specific standards but I won't spend time to document the process I want."

Allow me to clarify a few things:

- Format: we don't dictate format on docs. In terms of sharing important information, it's irrelevant. Dealer's choice.

- Audience: we are writing documents that are internal to our team, but also for consumption by other groups. Audience is engineering-focused.

- Consumption: we refer to documents as a way of learning all the things before asking uninformed questions to team members. RTFM is an expectation in my groups.

> instead of answering their very reasonable and pertinent questions you instead accuse them of being either incompetent or lazy.

These expectations aren't random; they are well-known, part of project deliverables, and non-negotiable. Existing projects show the quality of what's been produced in the past, to help with an understanding for anyone documenting what they've built and want us to depend on in production. After that, we definitely help those who still require help, but this isn't a surprise.

>Allow me top clarify a few things:

It was your story written by you on how you interact with engineers. I'm not the one you should be clarifying things to.

edit: The read I get is that a number of engineers fundamentally disagree with the value of your approach. As they're the ones who should be getting value from it based on your clarification that's a very bad sign.

I was thinking you were asking questions and/or engaging to understand, of which I've made an incorrect assumption.

"I don't know how" is the helpless version of the question that lazy children use to get out of shit they don't want to do. "Is there a audience I should write for / template I should use" is the clarifying version of the question someone who actually intends to do something asks.

As and engineer, sometimes getting started is the hardest part. But there are high quality, open source templates for almost anything in the documentation process available. I wish initiatives like The Good Docs Project would be more popular with engineers.

https://thegooddocsproject.dev

I don't understand, how is this even possible? If we don't understand:

1. the problem that we are solving 2. the input data 3. the process flow 4. the outcome

how do you even start coding?

> Docs should tell a story when you can

Depending on what the author means here, then please don't. I cannot work with documentation that attempt to convey technical information using a cute story. I don't care about Jim who's trying run a porn site, I just need to know how to configure mod_rewrite.

That's also why I could not get through "why's (poignant) Guide to Ruby", it might be the best thing ever written but I don't care for the fiction wrapper, it's distracting.

To each their own. One person's tedious or distracting is just what other people need to succeed.

(Source: I cannot stand watching videos when something can be conveyed via text. Nevertheless, that seems to be the way of the world these days. And I know folks who won't read anything if it could be a video instead. So it goes.)

> I cannot stand watching videos when something can be conveyed via text

I'm with you on that one, sadly YouTube pays better than your own blog.

I’m with you. Docs need to provide 2 things: the reference and specific examples. That’s it. Tell me what all the options are and what they do, then show me usage of as much realistic possibilities as possible.

> Know why you are creating your docs > Know who your target audience is > Know what their pain points are > Improve your docs over time

I think the biggest problem I've seen with docs is that we tend to overload docs with multiple, sometimes changing audiences in the hopes that fewer docs = less complexity and organizational debt to maintain. Unfortunately the result is that the doc is either too long or too high level to be useful to anyone. This is one of the areas where I actually think LLMs could deliver an actual paradigm shift (once we figure out design patterns that go beyond the suboptimal "ask your docs a question" implementations that exist today).

> once we figure out design patterns that go beyond the suboptimal "ask your docs a question" implementations that exist today

I'd love to hear more thoughts about this. We've added a LLM to let users ask questions of our docs and have found it very useful.

Somewhat surprisingly to me, it's also been useful to employees because it doesn't just answer the question, it also references the source, which includes GitHub issues, videos, docs and forum posts. This lets the employee or user dive in deeper to see if the underlying doc has more context or nuance. It also serves as a single entry point to all those sources, which is easier than visiting each.

As a rule, if you want something to get "more respect" in the business world, find a good way to tie it to business outcomes. That means instrumentation, and statistical modeling (because people only complain about these things when the relationship is hazy, indirect).

Mind elaborating more?

A statistical analysis is the definitive answer to the skeptic's question "Prove that docs deserve more respect." And to be able to answer that question you have to observe what happens to business outcomes with and without docs then perform a statistical test to see what the difference is, judged against its cost. It's thankless work, I imagine.

Lobbying like you've done with this essay is a probably a better investment of your time. Now you simply have to make sure the right people read it and decide to do it :)

I mean, in principle I don't disagree. A quantitative kpi that shows before and after is usually measured differently for each product you're building docs for.

For example, if you have a developer tool, the number of devs you can successfully onboard after you have solid documentation up and running is an effective strategy for getting unimaginative middle managers to understand the value.

Generally the people I work with have already come to the right conclusion because they have tried everything else and not gained the traction they believe their product deserves.

Experimental docs withdrawal? That sounds a bit too extreme and harmful for any business. Unless you had a different technique in mind.

If their utility is in question, then the company does not consider withdrawing them extreme! If it turns out to be harmful, QED! When you perform a statistical test, you only have to expose as many users to it for as long as needed to achieve statistical significance. Not all users will be affected; you need to be able to make a comparison.

The foregoing assumes the alternatives are having docs or not. If the alternatives are something else, such as having different kinds of documentation, then the test treatments will be chosen accordingly.

Would you do the same with, say, the UI? Or an API?

Again, you have to define the alternatives. APIs have launch success criteria too. One way to assess zero-to-one initiatives, if that is what you are asking about, is to start measuring before the project is complete. For a UI, that could be as soon as it is usable but before all the features are implemented. Then you will be able to able to estimate the value of the remaining features.

You might like to read https://hubbardresearch.com/publications/how-to-measure-anyt...

The need for some things to require statistical evidence and for others to be accepted wisdom, devoid of evidence or maybe a hand wave at most, is a form of politics itself. It is why we have agile, open plan offices and shite docs!

Docs metrics are worth so much. There's a tendency to overindex on support case deflection, which is often measuring a negative (how many support cases did we NOT get because self-service was so good). And if your docs are great, support is going to have fewer easy questions ("where do I find X? How do I get started with Y?") but more questions that require escalation earlier in their lifecycle ("I followed the great instructions but my obscure infrastructure gave me an inscrutable error message that applies only to me and no other customer").

I've often found that unsolicited customer sentiment is a hit, especially for customers won over from a competitor who either call the docs and self-service options a reason for switching or winning, or immediately call them out positively after switching.

In a holistic sense docs are also supportive for tech and retail support. They act as a reference, a knowledge base, and a place to point users.

Agreed. FWIW we technical writers (TWs) are well aware that we'd have more business-world respect if we could show more causation between our work and desired business outcomes. Turns out it's a tough nut to crack, judging by all the TWs I've seen work on this problem over the years without figuring out broadly scalable and repeatable systems. So we're stuck in this suboptimal zone where biz leaders know they can't get rid of us completely because Bad Things Clearly Happen More when you stop having someone dedicated to docs, but we often can't show compelling value beyond that.

There was a fascinating report last year suggesting that above-quality docs correlate with increased eng productivity across the board. My intuition says it's true but IMO we need to do more work proving that this connection is legit... the methodology and report writing itself is too complex: https://cloud.google.com/blog/products/devops-sre/deep-dive-...

One way to frame the business value of docs is equating it to design. Design is understood to be important, but not strictly tied to hard metrics. And the overall benefit is to improve the user experience. You can then measure more qualitatively.

You're not wrong, but FFS it gets old having to constantly justify your existence in a corporate structure unless you're in Sales. People don't get into technical writing to have to detour into instrumentation, stats modeling, etc. They want to do the work, not a bunch of work to justify doing the work that everybody (except executives) understand needs to be done.

Just once I'd like to see the burden put on decision makers to understand the needs of the business they run instead of having to make pretty decks they can pick over once a quarter when trying to figure out what line items to justify cutting to get a better bonus.

You can't do all this alone; you need allies. So use your communication skills to persuade a suitable sponsor with the power to assign the necessary resources. Google and DX regularly release reports about these things; e.g., https://getdx.com/blog/documentation-culture-engineering/

You could use them to raise awareness in your organization.

Perhaps add "Docs must be more than screenshots or follow-the-monkey instructions". If it's not appropriate to explain what the system is doing, it is then appropriate to link to something that does explain it.

Docs that say/show anything like "Select Enable VTd to enable the VTd function" are useless docs. I won't bother providing a list of docs that do exactly that, but start by looking at your BIOS help!! I think we can assume that I understand "click" and "enable", but we should also assume that only the project engineers understand the acronyms and special functions. How about "The VTd function (Intel's Virtual Technology - Direct IO) permits virtual machines to do IO with fewer buffer transfers. Virtual machines may run faster, but could corrupt disk."

I mean, sometimes that is exactly what is appropriate. For some use cases you just want clear step by step instructions. Sometimes you will want in depth technical explanations. That's really the point I made in that piece: you have to know who your audience is, and write accordingly.

I have found this framework helpful in thinking about the four kinds of docs: https://diataxis.fr/

* tutorials

* how-to guides

* reference

* explanation

>Docs should be tested - because you may be sure that everything is right, but without real users, like with any other product, you won't know for certain. Test it and test it again.

If you want to automate this, see: https://github.com/hitchdev/hitchstory

It is not a common approach, but generating how-to docs from tests can be almost unreasonably effective.

Kind of a bummer when the first thing you see is master pipelines failing

I'd love to learn more about your experience on doc gen from tests.

A few years ago I wrote a js lib that would read pupetteer - like commands and generate screenshots and videos of the sessions.

So you'd define a feature, a js file with commands like navigate To, click, etc, but with the added options of adding annotations (tool tips) and borders to elements on the page. The loaded page would also have a proxy cursor that would move nicely towards the element to be clicked, focused etc.

The end results are videos and screenshots that look like they have been made manually, but with no voice or audio, just interactions. The speed was slowed down as well to make them easy to follow along.

Then it would diff the screenshots with cached ones and discard if the changes were minimal (eg. timestamps).

I think I also did some markdown parsing as well, so that you'd write something like `feature:x step:5` in your markdown docs and it would replace it with the correct html to load the screenshot and/or video.

I really liked the end result, but having to write test-like code to generate screenshots and videos looked a bit weird. I didnt end up using it, but it's something I think about from time to time.

I've actually just been creating step by step markdown docs with screenshots with this approach but I love your idea of embedding annotations in videos with JS popups and a proxy cursor. Assuming playwright allows for it, I will experiment with this.

My experience has been that customers are usually just happy to get docs that are guaranteed up to date even if they're not very good. They seem receptive to the idea of writing YAML that generates this stuff too.

I think I might blow some minds if I combine this with your popups and maybe some AI generated voiceovers.

I wrote a book with a chapter on how to write docs for other people’s code https://howtoopensource.dev

I also wrote an open source tool for writing and testing tutorials https://github.com/zombocom/rundoc and another that will email you undocumented methods of open source code so you can practice writing documentation https://www.codetriage.com/.

I've written tons of docs in my day-- user-facing, developer facing, in between... It's much more difficult to write docs than people imagine, especially when they're merely making up for a poorly organized interface or user path. With the exception of developer docs for APIs, "about" info for datasets or projects, or tutorials introducing non-technical users to more technical concepts, almost every doc I've ever written was compensating for slipshod or poorly implemented design.

I agree with this take 1000%.

I remember a CTO at a startup I worked at who said "we want the product to be so intuitive that no docs are needed ". I think that is a lovely goal, but the truth is:

* People will anonymously scout docs to determine if your product can help them, especially if your docs are public but you require a sign up for your product (a very typical case)

* If public, docs are discoverable by Google, which means they are part of your marketing awareness effort

* Writing docs is cheaper than shipping code, and therefore can be worth implementing to compensate (as you wrote)

> People will anonymously scout docs to determine if your product can help them

Regular users don't do that: developers and techs do. That's what marketing material is for.

> If public, docs are discoverable by Google, which means they are part of your marketing awareness effort

Purpose-build marketing materials are better than technical documentation. They can contain technical information, but they serve a different purpose and work best when created for that

> Writing docs is cheaper than shipping code, and therefore can be worth implementing to compensate (as you wrote)

Sure, doing a bad job is usually cheaper than doing a good job, but if you do a good job designing your interface, and you do a good job creating marketing material, there's no comparison. Trying to shave pennies off of marketing material, especially, is about as penny-wise and pound foolish as you get. Your average end user probably reads exactly zero lines of formal software documentation in their entire lives, and that probably has a lot more psychological inertia with them than interest in your product. Even if it's well-written, they're not used to it. They find it intimidating and off-putting; using it as marketing material with it is a surefire way to turn off a whole lot of potential customers. It would be like a nightclub trying to save money by firing the models they pay to hand out flyers and hiring a couple extra hulking, chipped-tooth bouncers to pick up the slack-- it's not like there's any technical reason they can't do it, and it's the same flyer either way, right?

Let the appropriate professionals ply the expertise they went to school for and built their career on rather than pushing that onto a developer who only thinks they can sub in as a technical writer and interface designer because they don't quite understand what those people add to the process: they just know how its technically implemented. I was that developer for years before I went to school for design. Devs really really can't intuit their way through those processes like they assume they can- That's why damn near any FOSS that's been taken up by non-technical crowds is controlled by foundations or corporations with professional designers and writers.

As the post says, docs are part of any software product. This cannot be emphasized enough. A technical product without documentation or effective UX writing is going to generate so much dissatisfaction and support burden you'll consider shutting it down. And yes, as twodave wrote, writing docs is when you discover users' pains.

How you serve docs depends on the product itself: it'd be in-product views, a site, even CLI output. It doesn't matter as long as you've a content strategy for self-service support and people who can dedicate their time to producing the docs.

Don't give up on docs: hire someone to write them and take care of their strategy.

Love that you are paying docs more respect by giving people a leg up on how to write docs right. This isn't talked about enough as far as I know.

I will offer a point on the headline... I agree with you that docs deserve more respect, but I also think that you and I (and likely many HN readers) are a biased sample. The average user (of a non-technical product) spends a lot less time reading docs than we all probably think they do.

Docs are respected proportionally to the amount of value that can be ascribed to them. I think that value is unfortunately undercounted, but people seem to be consistently valuing "docs" in the $ resourced against them and the attention paid.

It's really dependant on the industry. Docs for a retail audience get low usage. Docs for developer tooling get high usage. It's a whole spectrum.

As for the title, well, it's a draw for the reader and needs to be spicy. Really when I wrote it, I meant from an organizational or project perspective.

As you posted a link from your own blog/consulting, I will allow myself a design comment, this slowly appearing text makes reading extremely distracting on a phone. And the font is smaller than most websites.

Fixed. Appreciated the feedback.

Much better! Thanks

My experience has been that it’s extremely difficult to get to great docs even when you do want to invest in them. I really value excellent documentation. I would absolutely kill for a quality overhaul of our various products’ documentation (see: docs.auxon.io).

We only sell to large enterprises & very technical orgs, so to get around middling or confusing documentation what we end up doing is a lot of quickly curated videos that directly address the customer’s specific need, but it absolutely doesn’t scale well, and I am certain that a variety of tutorials, cookbooks, and reference docs would be extremely useful.

I have always found documentation to be critical.

The most important lessons that I've learned, are how to "balance" my docs, and integrate them into the code, itself, if possible.

Here's my take on documentation: https://littlegreenviper.com/miscellany/leaving-a-legacy/

Documentation is psedocode to me.

I've given up on docs. The only thing that really works are typesystems and, to some degree, inline tests/documentation that lives next to the code and is compiled there.

The article is mostly for customer-facing docs. Think "user manual".

Really, the article is about UX more than anything.

Reply on news.ycombinator.com