6 ms·

Treating documentation like a product

106 points by shahednasser 4y ago

remoquete 4y ago
Nice write-up. The title reminds me of a modern tech writing classic, “The Product is Docs”: https://www.amazon.com/Product-Docs-technical-documentation-development-ebook/dp/B085KHTV95 https://www.amazon.com/Product-Docs-technical-documentation-... In general, I’d like to see more companies treating documentation as a first class product, with dedicated technical resources and product management team. I wrote about that in a post presenting what I call the “Docs Hierarchy of Needs”: https://passo.uno/docs-hierarchy-of-needs/ https://passo.uno/docs-hierarchy-of-needs/
- m0llusk 4y ago
  Potentially interesting that the E-Myth series of books on entrepreneurship essentially asserts that the company itself is documentation because processes that can be readily and reliably communicated to employees are at the core of consistent value generating operations.
kinggencha 4y ago
Putting animated GIFs into your documentation or blog articles, negatively impacts legibility. The constant movement diverts attention and makes people skip that section so they can just scroll the annoyance out of view. If you MUST include animated guidance for whatever reason, use videos that have playback controls and are paused by default. Seeing this in an article on how to improve documentation makes me question any message you might try to get across.
- remoquete 4y ago
  There are ways of adding reproduction controls to animated GIFs. Animations have their place and purpose depending on the type of documentation, especially when you want to illustrate some complex steps.
  - autoexec 4y ago
    When is an animated GIF showing a series of complex steps better than a video of the same? The video has the advantage of offering things like audio, higher quality playback, the ability to be downloaded locally and played in VLC (where you can do things like zoom in or slow it down), etc. Maybe not all of those things are needed in every case, but even then video will get the job done just as well as a GIF and provide consistency with any instance where you do end up needing video's features.
    - remoquete 4y ago
      For steps that take less than 10 seconds, I’m not sure a video would prove superior; GIFs are easier to produce and easier to publish. Then again, I’m also pro-videos. Edit: typo
    - euroderf 4y ago
      I for one am a text person, and for me video is death - the end of my attention. Very very few videos use my time as effectively as I can when I am setting the pace and maybe deciding when and how to skip around. Give me (please) well-done illustrations.
      - autoexec 4y ago
        I agree that if something can be explained in text I'd much prefer it over a video, but if you need (or expect some people will need) to see a video a GIF seems like the weaker option for how to present that.
        euroderf 4y ago
        If you're given a task that is not obvious and requires pauses for familiarization at several steps, isn't it easier to deal with text+illustrations than with video ?
    - NikolaNovak 4y ago
      Inertia maybe? A web page peppered with video controls and blocks seems busy and distracting to me. It feels like heaviness, bloat and overhead (even if technically it isn't). A couple of GIF animations showing simple actions works for me. So it may be more subjective than objective?
- shahednasser 4y ago
  Thank you for your opinion. We actually don't use GIFs in our documentation and are limiting the use of screenshots and similar visual assets as it can go stale easily. We do rely on videos where necessary.
- deleted 4y ago
  [deleted]
nonethewiser 4y ago
Probably an unpopular opinion, but if you want rock solid documentation, switch to waterfall. I just dont think its possible with agile. It's always lacking. There are degrees of quality, sure. Aspire for good documentation. But there are too many moving parts by too many hands and there are diminishing returns on documentation efforts. Also consider that every piece of documentation you write adds onto the documentation burden. The more you document, or the more specificity you give in documentation, the harder it is to have accurate docs. Auto-generating stuff gets around this but is usually of limited value.
- tremon 4y ago
  Of course it is possible with agile, it "just" needs to be properly prioritized. And that also means, in good Agile fashion, that documentation skills needs to be represented in the team. If you don't prioritize documentation and do not value technical writing skills, it doesn't matter whether if you use waterfall or agile processes, you will still end up with sub-par documentation. Also, what kind of documentation? High-level design documentation? Low-level code documentation? Code structure reading guides? End-user manuals? Elevator-style sales flyers?
  - j45 4y ago
    Documentation in some ways is more of an important output than code. Documentation serves to to create beginners with the source code and project. When working with devs it’s made clear that what they are delivering is documentation of which working code is one part. The ability to write sentences in documentation is as important as writing code. Writing as one works (not after) and then editing is one of the only ways I’ve found that there is a chance, waterfall, agile or cowboy.
- deleted 4y ago
  [deleted]
- simonw 4y ago
  Keep your docs in the same repository as your code and enforce relevant documentation updates as part of the code review progress. Works great.
Hakashiro 4y ago
Documentation has always been part of the product. Documentation has always been part of the coding, not an afterthought, not an optional thing, not a second-class citizen. This is how I was taught in university. I'm still baffled to see how many developers believe the key to professional success is writing a lot of computer code, as fast and as efficiently as possible. Then you go to their GitHub repos for their personal projects and they're completely unusable because you don't even get installation instructions. Best case scenario you will get an auto-install script that works on Debian 9 and has been unmaintained for years, but at least you can read what it's doing and adapt it to your distribution of choice. Complete insanity.
- deleted 4y ago
  [deleted]
- garganzol 4y ago
  Probably not insanity, just an omission. It will be gradually improved over time by those people as they mature.
- rprospero 4y ago
  I had a classmate who got hit with this issue from the opposite direction. In our first semester CS course, 70% of our grade was based on our documentation. My classmate wrote beautiful, comprehensive documentation of the solution program to each solution set. They also didn't write a single line of code the entire semester, passing the class entirely on the strength of how they documented software that wouldn't even compile. By the time that they reached the more advanced courses, where producing a working program was a requirement, they were so far behind that continuing in the program was hopeless (e.g. being asked to write a database when they'd never even attempted "Hello, World"). If the department counsellors had been on the ball, my classmate would have made an amazing technical writer, but I believe they wound up switching to electrical engineering.
- trynewideas 4y ago
  > I'm still baffled to see how many developers believe the key to professional success is writing a lot of computer code, as fast and as efficiently as possible. I wonder if developers tend to believe this, or if leadership incentivizes it, either explicitly[1] or implicitly. 1: https://www.platformer.news/p/twitter-braces-for-layoffs https://www.platformer.news/p/twitter-braces-for-layoffs > Rezaei tried to rally the troops, telling engineers to focus on shipping code as quickly as possible: > "So if you ask what should I do now: do good engineering work. Write code. Fix bugs, keep the site up. I know the criteria for being at Twitter is that. It’s not working on a fancy project for Elon. The good culture change is, it’s shipping and delivering. I encourage you to rotate more on coding and shipping, and less on documentation, planning, strategy etc. If you want to be in a “special” group this week, code and ship 5x as [much as] before. ..."
intrasight 4y ago
The documentation IS the product. As a top Navy brass once said "A nuclear destroyer is a floating SGML document". The best software companies have a dedicated team of technical writers and their own chain of command and comparable salaries to coders.
- j45 4y ago
  Well said. In addition to writers on the team it’s important to ensure all developers are writing and developing their writing skills as much as coding skills.
- tejohnso 4y ago
  > The best software companies have a dedicated team of technical writers and their own chain of command and comparable salaries to coders Can you provide some examples? I've never seen a technical writer job post on this site as an individual post, and I don't see a single mention of documentation work in the recent Who's Hiring post.
  - habosa 4y ago
    The Google developer relations team has hundreds of tech writers, they have their own career ladder alongside developer relations engineers.
  - giraffe_lady 4y ago
    This site isn't representative of all software jobs, or all software companies by any means. That said I've also very rarely seen a posting for this. I've worked at a few companies that had 1-3 people doing it full time. But in every case I can think of they were exceptionally competent individuals who had started off in either support or engineering and gradually took it on as an explicit role because they were willing to do it and once they were the value was obvious.
  - mikelevins 4y ago
    Apple and Cisco are two examples of companies with large, well-organized technical documentation teams. I've worked on both teams. There are certainly many other examples. I've also worked for a few startups on setting up their technical documentation processes. My career in software started January 1, 1988 at Apple. Roughly 1/3 of my career has been as a technical writer, and 2/3 as a programmer. The two disciplines require comparable levels of knowledge and technical skills, but programming generally gets much better funding and other support. There are several reasons for that. The most obvious is that you can't ship a software product without some programming, but you can ship one without any technical writing. It's generally a bad idea, but it's possible. Another reason is that technical documentation is in almost all cases a pure cost center. You don't make money from your technical docs. Worse, you can always make docs better with more effort, so there's no theoretical ceiling on its cost. How expensive are docs? Well, how much have you got? Yet another reason that docs get short shrift is that smart people tend to assume that they can write. They are often mistaken. Among professional tech writers and editors, "engineering documentation" is a pejorative phrase. Nobody thinks that they can write good software with no experience and no training, but many otherwise intelligent people make exactly that assumption about tech docs. Also, it must be said that technical documentation is probably the least cool job in software, even less cool than compatibility testing. Nobody ever called a tech writer a "rock star" (although I can think of a couple that probably qualify). I haven't seen a lot of hiring posts for tech writers on HN, either, but that doesn't surprise me. HN is sort of startup-oriented, and it usually takes startups a while to realize that they need professional tech writers. It happens when someone realizes that they're spending too much supporting customers and partners because they're not spending enough on docs. That's when they go shopping around for someone to help them fix that problem. I've been that guy before, and I also know a good recruiter who specializes in that, in case anyone needs a contact.
deleted 4y ago
[deleted]
2devnull 4y ago
Documentation > tests > code People do this backward.

106 points by shahednasser 4y ago

Nice write-up. The title reminds me of a modern tech writing classic, “The Product is Docs”: https://www.amazon.com/Product-Docs-technical-documentation-development-ebook/dp/B085KHTV95 https://www.amazon.com/Product-Docs-technical-documentation-... In general, I’d like to see more companies treating documentation as a first class product, with dedicated technical resources and product management team. I wrote about that in a post presenting what I call the “Docs Hierarchy of Needs”: https://passo.uno/docs-hierarchy-of-needs/ https://passo.uno/docs-hierarchy-of-needs/

m0llusk 4y ago
Potentially interesting that the E-Myth series of books on entrepreneurship essentially asserts that the company itself is documentation because processes that can be readily and reliably communicated to employees are at the core of consistent value generating operations.

kinggencha 4y ago

Putting animated GIFs into your documentation or blog articles, negatively impacts legibility. The constant movement diverts attention and makes people skip that section so they can just scroll the annoyance out of view. If you MUST include animated guidance for whatever reason, use videos that have playback controls and are paused by default. Seeing this in an article on how to improve documentation makes me question any message you might try to get across.

remoquete 4y ago
There are ways of adding reproduction controls to animated GIFs. Animations have their place and purpose depending on the type of documentation, especially when you want to illustrate some complex steps.
- autoexec 4y ago
  When is an animated GIF showing a series of complex steps better than a video of the same? The video has the advantage of offering things like audio, higher quality playback, the ability to be downloaded locally and played in VLC (where you can do things like zoom in or slow it down), etc. Maybe not all of those things are needed in every case, but even then video will get the job done just as well as a GIF and provide consistency with any instance where you do end up needing video's features.
  - remoquete 4y ago
    For steps that take less than 10 seconds, I’m not sure a video would prove superior; GIFs are easier to produce and easier to publish. Then again, I’m also pro-videos. Edit: typo
  - euroderf 4y ago
    I for one am a text person, and for me video is death - the end of my attention. Very very few videos use my time as effectively as I can when I am setting the pace and maybe deciding when and how to skip around. Give me (please) well-done illustrations.
    - autoexec 4y ago
      I agree that if something can be explained in text I'd much prefer it over a video, but if you need (or expect some people will need) to see a video a GIF seems like the weaker option for how to present that.
      - euroderf 4y ago
        If you're given a task that is not obvious and requires pauses for familiarization at several steps, isn't it easier to deal with text+illustrations than with video ?
  - NikolaNovak 4y ago
    Inertia maybe? A web page peppered with video controls and blocks seems busy and distracting to me. It feels like heaviness, bloat and overhead (even if technically it isn't). A couple of GIF animations showing simple actions works for me. So it may be more subjective than objective?
shahednasser 4y ago
Thank you for your opinion. We actually don't use GIFs in our documentation and are limiting the use of screenshots and similar visual assets as it can go stale easily. We do rely on videos where necessary.
deleted 4y ago
[deleted]

nonethewiser 4y ago

Probably an unpopular opinion, but if you want rock solid documentation, switch to waterfall. I just dont think its possible with agile. It's always lacking. There are degrees of quality, sure. Aspire for good documentation. But there are too many moving parts by too many hands and there are diminishing returns on documentation efforts. Also consider that every piece of documentation you write adds onto the documentation burden. The more you document, or the more specificity you give in documentation, the harder it is to have accurate docs. Auto-generating stuff gets around this but is usually of limited value.

tremon 4y ago
Of course it is possible with agile, it "just" needs to be properly prioritized. And that also means, in good Agile fashion, that documentation skills needs to be represented in the team. If you don't prioritize documentation and do not value technical writing skills, it doesn't matter whether if you use waterfall or agile processes, you will still end up with sub-par documentation. Also, what kind of documentation? High-level design documentation? Low-level code documentation? Code structure reading guides? End-user manuals? Elevator-style sales flyers?
- j45 4y ago
  Documentation in some ways is more of an important output than code. Documentation serves to to create beginners with the source code and project. When working with devs it’s made clear that what they are delivering is documentation of which working code is one part. The ability to write sentences in documentation is as important as writing code. Writing as one works (not after) and then editing is one of the only ways I’ve found that there is a chance, waterfall, agile or cowboy.
deleted 4y ago
[deleted]
simonw 4y ago
Keep your docs in the same repository as your code and enforce relevant documentation updates as part of the code review progress. Works great.

Hakashiro 4y ago

Documentation has always been part of the product. Documentation has always been part of the coding, not an afterthought, not an optional thing, not a second-class citizen. This is how I was taught in university. I'm still baffled to see how many developers believe the key to professional success is writing a lot of computer code, as fast and as efficiently as possible. Then you go to their GitHub repos for their personal projects and they're completely unusable because you don't even get installation instructions. Best case scenario you will get an auto-install script that works on Debian 9 and has been unmaintained for years, but at least you can read what it's doing and adapt it to your distribution of choice. Complete insanity.

deleted 4y ago
[deleted]
garganzol 4y ago
Probably not insanity, just an omission. It will be gradually improved over time by those people as they mature.
rprospero 4y ago
I had a classmate who got hit with this issue from the opposite direction. In our first semester CS course, 70% of our grade was based on our documentation. My classmate wrote beautiful, comprehensive documentation of the solution program to each solution set. They also didn't write a single line of code the entire semester, passing the class entirely on the strength of how they documented software that wouldn't even compile. By the time that they reached the more advanced courses, where producing a working program was a requirement, they were so far behind that continuing in the program was hopeless (e.g. being asked to write a database when they'd never even attempted "Hello, World"). If the department counsellors had been on the ball, my classmate would have made an amazing technical writer, but I believe they wound up switching to electrical engineering.
trynewideas 4y ago
> I'm still baffled to see how many developers believe the key to professional success is writing a lot of computer code, as fast and as efficiently as possible. I wonder if developers tend to believe this, or if leadership incentivizes it, either explicitly[1] or implicitly. 1: https://www.platformer.news/p/twitter-braces-for-layoffs https://www.platformer.news/p/twitter-braces-for-layoffs > Rezaei tried to rally the troops, telling engineers to focus on shipping code as quickly as possible: > "So if you ask what should I do now: do good engineering work. Write code. Fix bugs, keep the site up. I know the criteria for being at Twitter is that. It’s not working on a fancy project for Elon. The good culture change is, it’s shipping and delivering. I encourage you to rotate more on coding and shipping, and less on documentation, planning, strategy etc. If you want to be in a “special” group this week, code and ship 5x as [much as] before. ..."

intrasight 4y ago

The documentation IS the product. As a top Navy brass once said "A nuclear destroyer is a floating SGML document". The best software companies have a dedicated team of technical writers and their own chain of command and comparable salaries to coders.

j45 4y ago
Well said. In addition to writers on the team it’s important to ensure all developers are writing and developing their writing skills as much as coding skills.
tejohnso 4y ago
> The best software companies have a dedicated team of technical writers and their own chain of command and comparable salaries to coders Can you provide some examples? I've never seen a technical writer job post on this site as an individual post, and I don't see a single mention of documentation work in the recent Who's Hiring post.
- habosa 4y ago
  The Google developer relations team has hundreds of tech writers, they have their own career ladder alongside developer relations engineers.
- giraffe_lady 4y ago
  This site isn't representative of all software jobs, or all software companies by any means. That said I've also very rarely seen a posting for this. I've worked at a few companies that had 1-3 people doing it full time. But in every case I can think of they were exceptionally competent individuals who had started off in either support or engineering and gradually took it on as an explicit role because they were willing to do it and once they were the value was obvious.
- mikelevins 4y ago
  Apple and Cisco are two examples of companies with large, well-organized technical documentation teams. I've worked on both teams. There are certainly many other examples. I've also worked for a few startups on setting up their technical documentation processes. My career in software started January 1, 1988 at Apple. Roughly 1/3 of my career has been as a technical writer, and 2/3 as a programmer. The two disciplines require comparable levels of knowledge and technical skills, but programming generally gets much better funding and other support. There are several reasons for that. The most obvious is that you can't ship a software product without some programming, but you can ship one without any technical writing. It's generally a bad idea, but it's possible. Another reason is that technical documentation is in almost all cases a pure cost center. You don't make money from your technical docs. Worse, you can always make docs better with more effort, so there's no theoretical ceiling on its cost. How expensive are docs? Well, how much have you got? Yet another reason that docs get short shrift is that smart people tend to assume that they can write. They are often mistaken. Among professional tech writers and editors, "engineering documentation" is a pejorative phrase. Nobody thinks that they can write good software with no experience and no training, but many otherwise intelligent people make exactly that assumption about tech docs. Also, it must be said that technical documentation is probably the least cool job in software, even less cool than compatibility testing. Nobody ever called a tech writer a "rock star" (although I can think of a couple that probably qualify). I haven't seen a lot of hiring posts for tech writers on HN, either, but that doesn't surprise me. HN is sort of startup-oriented, and it usually takes startups a while to realize that they need professional tech writers. It happens when someone realizes that they're spending too much supporting customers and partners because they're not spending enough on docs. That's when they go shopping around for someone to help them fix that problem. I've been that guy before, and I also know a good recruiter who specializes in that, in case anyone needs a contact.

deleted 4y ago

[deleted]

2devnull 4y ago

Documentation > tests > code People do this backward.