8 ms·

Docs Deserve More Respect

104 points by ramijames 3y ago

esafak 3y ago
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).
- ramijames 3y ago
  Mind elaborating more?
  - esafak 3y ago
    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 :)
    - ramijames 3y ago
      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.
    - remoquete 3y ago
      Experimental docs withdrawal? That sounds a bit too extreme and harmful for any business. Unless you had a different technique in mind.
      - esafak 3y ago
        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.
        remoquete 3y ago
        Would you do the same with, say, the UI? Or an API?
        esafak 3y ago
        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-anything-book/ https://hubbardresearch.com/publications/how-to-measure-anyt...
    - quickthrower2 3y ago
      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!
- starkparker 3y ago
  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.
  - ramijames 3y ago
    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.
- kaycebasques 3y ago
  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-into-2022-state-of-devops-report-on-documentation https://cloud.google.com/blog/products/devops-sre/deep-dive-...
- nimbus3001 3y ago
  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.
- jzb 3y ago
  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.
  - esafak 3y ago
    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/ https://getdx.com/blog/documentation-culture-engineering/ You could use them to raise awareness in your organization.
ta988 3y ago
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.
- ramijames 3y ago
  Fixed. Appreciated the feedback.
  - ta988 3y ago
    Much better! Thanks
kyawzazaw 3y ago
[dead]
kbos87 3y ago
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.
- ramijames 3y ago
  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.
drpixie 3y ago
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."
- ramijames 3y ago
  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.
- mooreds 3y ago
  I have found this framework helpful in thinking about the four kinds of docs: https://diataxis.fr/ https://diataxis.fr/ * tutorials * how-to guides * reference * explanation
chefandy 3y ago
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.
- ramijames 3y ago
  I agree with this take 1000%.
- mooreds 3y ago
  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)
  - chefandy 3y ago
    > 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.
twodave 3y ago
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'".
- applecrazy 3y ago
  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-prfaq-for-product-innovation/ https://productstrategy.co/working-backwards-the-amazon-prfa...
- ramijames 3y ago
  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.
- slavik81 3y ago
tqi 3y ago
> 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).
- mooreds 3y ago
  > 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.
im_down_w_otp 3y ago
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.
valenterry 3y ago
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.
- GuB-42 3y ago
  The article is mostly for customer-facing docs. Think "user manual". Really, the article is about UX more than anything.
hitchstory 3y ago
>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 https://github.com/hitchdev/hitchstory It is not a common approach, but generating how-to docs from tests can be almost unreasonably effective.
- ramon156 3y ago
  Kind of a bummer when the first thing you see is master pipelines failing
- rudasn 3y ago
  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.
  - hitchstory 3y ago
    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.
schneems 3y ago
I wrote a book with a chapter on how to write docs for other people’s code https://howtoopensource.dev https://howtoopensource.dev I also wrote an open source tool for writing and testing tutorials https://github.com/zombocom/rundoc 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/ https://www.codetriage.com/.
remoquete 3y ago
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.
BeerSheva 3y ago
[flagged]
ChrisMarshallNY 3y ago
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/ https://littlegreenviper.com/miscellany/leaving-a-legacy/
revskill 3y ago
Documentation is psedocode to me.
jroseattle 3y ago
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.
- marcinzm 3y ago
  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.
  - wahnfrieden 3y ago
    This is why companies are starting to replace more middle manager roles with ICs
  - jzb 3y ago
    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."
mrweasel 3y ago
> 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.
- jzb 3y ago
  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.)
  - mrweasel 3y ago
    > 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.
- twodave 3y ago
  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.

104 points by ramijames 3y ago

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).

ramijames 3y ago
Mind elaborating more?
- esafak 3y ago
  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 :)
  - ramijames 3y ago
    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.
  - remoquete 3y ago
    Experimental docs withdrawal? That sounds a bit too extreme and harmful for any business. Unless you had a different technique in mind.
    - esafak 3y ago
      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.
      - remoquete 3y ago
        Would you do the same with, say, the UI? Or an API?
        esafak 3y ago
        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-anything-book/ https://hubbardresearch.com/publications/how-to-measure-anyt...
  - quickthrower2 3y ago
    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!
starkparker 3y ago
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.
- ramijames 3y ago
  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.
kaycebasques 3y ago
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-into-2022-state-of-devops-report-on-documentation https://cloud.google.com/blog/products/devops-sre/deep-dive-...
nimbus3001 3y ago
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.
jzb 3y ago
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.
- esafak 3y ago
  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/ https://getdx.com/blog/documentation-culture-engineering/ You could use them to raise awareness in your organization.

ta988 3y ago

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.

ramijames 3y ago
Fixed. Appreciated the feedback.
- ta988 3y ago
  Much better! Thanks

kyawzazaw 3y ago

[dead]

kbos87 3y ago

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.

ramijames 3y ago
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.

drpixie 3y ago

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."

ramijames 3y ago
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.
mooreds 3y ago
I have found this framework helpful in thinking about the four kinds of docs: https://diataxis.fr/ https://diataxis.fr/ * tutorials * how-to guides * reference * explanation

chefandy 3y ago

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.

ramijames 3y ago
I agree with this take 1000%.
mooreds 3y ago
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)
- chefandy 3y ago
  > 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.

twodave 3y ago

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'".

applecrazy 3y ago
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-prfaq-for-product-innovation/ https://productstrategy.co/working-backwards-the-amazon-prfa...
ramijames 3y ago
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.
slavik81 3y ago

tqi 3y ago

> 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).

mooreds 3y ago
> 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.

im_down_w_otp 3y ago

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.

valenterry 3y ago

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.

GuB-42 3y ago
The article is mostly for customer-facing docs. Think "user manual". Really, the article is about UX more than anything.

hitchstory 3y ago

>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 https://github.com/hitchdev/hitchstory It is not a common approach, but generating how-to docs from tests can be almost unreasonably effective.

ramon156 3y ago
Kind of a bummer when the first thing you see is master pipelines failing
rudasn 3y ago
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.
- hitchstory 3y ago
  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.

schneems 3y ago

I wrote a book with a chapter on how to write docs for other people’s code https://howtoopensource.dev https://howtoopensource.dev I also wrote an open source tool for writing and testing tutorials https://github.com/zombocom/rundoc 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/ https://www.codetriage.com/.

remoquete 3y ago

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.

BeerSheva 3y ago

[flagged]

ChrisMarshallNY 3y ago

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/ https://littlegreenviper.com/miscellany/leaving-a-legacy/

revskill 3y ago

Documentation is psedocode to me.

jroseattle 3y ago

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.

marcinzm 3y ago
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.
- wahnfrieden 3y ago
  This is why companies are starting to replace more middle manager roles with ICs
- jzb 3y ago
  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."

mrweasel 3y ago

> 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.

jzb 3y ago
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.)
- mrweasel 3y ago
  > 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.
twodave 3y ago
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.