[ebiester]

I would suggest introducing two things.

First, introduce The Diataxis framework ( https://diataxis.fr/ ) for documentation. It makes people think about documentation in a more structured way, and allows you to be more specific in the types of missing documentation. (High documentation cultures are often good with explanation but not tutorials, for example.)

Second, I would introduct the idea of a Documentation Portfolio. I have a review of Agile Documentation at https://www.ebiester.com/documentation/2020/06/02/agile-docu... and it speaks to another structure for how to build the documentation in a more reliable form and thinking more carefully about your audience for a particular type of documentation.

[mr_gibbins]

I'm sure these are great technological answers but this problem can be solved simply and quickly by a human.

Not every issue needs to be solved by a butter robot.

Why not employ a technical writer/documenter/whatever job title you like, even as a temp, whose sole job is to sort out the mess of documentation you have and then to write new documentation as you move forward?

[ericmay]

> Why not employ a technical writer/documenter/whatever job title you like

Primarily because it's a far, far more complicated job than that and you can't really hire someone off the street to do it effectively. Typically in a tech company a tech writer is going to know almost as much or more (after years of experience diving into every detail) about a given technology or application or API, and so that begs the question why not make twice as much working as a software developer and not have to sort out these types of messes?

Also job security. Anyone doing this work full-time is the first on the chopping block, and developers who are working on documentation tend to be perceived as lower status since they aren't delivering features.

[Viliam1234]

You explained why no one wants to take the job in the typical company. They would be disrespected, and likely soon fired.

But a different question is, why is no company trying to do this differently? Like, hiring one good tech writer to maintain the company documentation, and paying them as much as they pay the developers.

[stevesimmons]

> But a different question is, why is no company trying to do this differently?

I once worked at a company - in a different domain - that made a conscious decision to make this kind of hire. It worked incredibly well, and I never understood why more companies didn't do it.

The context in my case was the Australian offices of a management consulting firm (BCG). The Melbourne and Sydney offices hired what were called "editors", brought on at the same grade as the consultants. Not editing as in correcting grammar. But helping the consultants improve the logic of the arguments in their slide decks: so they were logically consistent, easy to understand, and actually addressed the clients' issues. I was a junior consultant back then, and we were constantly pushed by our managers "have you seen Yvonne?" [the Melbourne editor] when preparing for major presentations.

[SilasX]

I would love that job, I'm always going back to presentations and finding better ways they could have made the point and identifying missing context what they would need to be more relevant.

[brendank310]

A previous team I was on ended up with this role. Strong writer with no technical skills joined the team and worked hand-in-hand with engineers fleshing out docs. It was productive for the engineers because they needed to articulate the ideas very clearly. The writer has been attached to that project now for 6-7 years at this point, and could probably stand in as a support engineer for some problems. It was a little painful getting HR to approve a tech writer getting paid close to an engineer position (this was after a few years).

I do like the sibling comment calling for a librarian. I imagine that would pay a ton of dividends if the librarian was motivated and got support.

[innocentoldguy]

Some companies do value technical writers and pay them as much as engineers, but they are still pretty rare.

There are three things that I think are preventing technical writing from being more widely valued:

1. Software companies tend not to distinguish between technical writers who are good at English vs. technical writers who are good at engineering, understand their audience, and can articulate complex ideas to that audience effectively.

2. Technical writers who are good at English make about half as much as technical writers with engineering skills, but they also muddy the hiring waters and drag salaries down for everyone else.

3. Most corporate-people think because they can type up a decent email they can write technical documentation themselves. They're usually wrong on both counts.

[dividefuel]

As a tech writer, I think this is because it's hard to concretely quantify the value that a tech writer brings, and thus it's hard to make a clear business case for.

[CrypticShift]

> differently? Like, hiring one good tech writer to maintain the company documentation

He assumes that "full understanding (into every detail) of what is being documented is needed" (as I put it). So, the new hire will never get it right 100%. he will both struggle and annoy others (to forever enlighten him), which is a fair point.

But it is not black or white. Others here have more positive experiences

[DoingIsLearning]

Probably not the same pay as developers but the scenario you describe is already true in most regulated industries, where some regulated body actually asks for the docs on any given product.

[innocentoldguy]

> Primarily because it's a far, far more complicated job than that and you can't really hire someone off the street to do it effectively.

This comment is absolutely true and many, of not most, companies fail to understand it. I think the problem stems from corporate-people thinking, "Why should I pay a writer when we all speak English (or whatever language) and can write it ourselves." And that's why so many companies have shitty documentation.

> ...so that begs the question why not make twice as much working as a software developer and not have to sort out these types of messes?

I was a software engineer for 30+ years and got completely burned out on it, so I left engineering to do technical writing. So far, I like it much better because I have far more control over my time. In my experience so far, the sorting-out-messes work is about the same in either field. Both jobs are pretty complex. I also make exactly the same as I did while working as an engineer.

I think the secret to not being first on the chopping block is to show you're delivering value to customers and internal teams. At least I attribute that to my survival through multiple layoffs so far.

[bentcorner]

> I was a software engineer for 30+ years and got completely burned out on it, so I left engineering to do technical writing

How did you make this transition? Any credentials/certifications you needed? Did you transition within the same company?

[innocentoldguy]

My college degree was in writing, so I used that and a portfolio to make the transition. During interviews, it seems my software engineering experience and portfolio are more valued than my writing degree though.

[CrypticShift]

Summary: HIGH Documentation = HIGH staleness + HIGH loss. HIGH staleness is because nobody wants to do it (status is lower). Also… nobody else can do it (full understanding of what is being documented is needed)

So, to solve the first staleness part, there is only two ways: raise the documenter status, or make it somewhat possible (easier?) for someone else to do at least a part of it. are they both really that hopeless?

PS: to solve the second loss/discovery part, I think we are heading for that AI powered simple "unified search" experience.

[beckingz]

AI can't solve search. If you look at how google did it, they bullied and cajoled site owners to add detailed metadata to the top of pages. It's not magic, it's creating incentives for people to create documentation.

[spencerchubb]

'bullied and cajoled' is an interesting set of verbs to use here. Is there a reason not to use metadata? Doesn't it make the web easier to index, and therefore easier for everyone to use?

[midoridensha]

>Is there a reason not to use metadata? Doesn't it make the web easier to index, and therefore easier for everyone to use?

Yes, there's a very good reason not to use metadata: it's extra work, and it's not very fun, just like writing docs for software. So people don't want to do it because it isn't "sexy" (and there aren't very good incentives to overcome people's reluctance to do that work).

Because of this, just like any job that people don't really want to do, you have to "bully and cajole" them into doing it.

[beckingz]

A human has to write this type of metadata.

If you don't include the right metadata, google won't rank you highly. If you include the right metadata, your content will get higher rankings and the snazzy preview cards on different social media platforms.

Metadata is good! There are structural incentives to be mediocre though.

[thepawn1]

The age old issue. There's oodles of data at how people don't keep doing it because it's toil to them.

[mycall]

The better question to ask is if AI can do the ghost writing that high-documentation culture needs. This is an interesting hypothesis for GPT-4

[CrypticShift]

First, I’m assuming the documentation is already updated (i.e., 1st part is OK = no staleness)

Second, the whole point of AI NLP search (i.e., 2nd part = loss) is that it does not need metadata (which was the basis of the now mostly abandoned semantic web approach to KM).

[bloaf]

You need to

1) Link to the documentation in your tools

2) Ensure everyone has edit access to the linked documents

[euroderf]

A feature of docs-as-code is having the (typ. markdown) docs live in the code directories. Leaving no excuses for tech people not to update them, or at least insert a TODO.

Another idea might be, whenever a new feature is closed out, auto-allocate some percentage of its implementation time to documentation, and schedule an interview with a tech writer.

[ghaff]

What you probably really want is a librarian (with some degree of technical background). We at least had one for a while for our sales/marketing docs--which are separate from customer-facing technical docs.

[gopher_space]

> Primarily because it's a far, far more complicated job than that and you can't really hire someone off the street to do it effectively.

Library science is a popular area of study but the job market isn’t great and neither is the pay. Lots of people to choose from here even without poaching from existing libraries.

[spoils19]

> you can't really hire someone off the street to do it effectively.

I disagree, I've been apart of a few companies that have done exactly this. I would suggest not presenting this argument as an absolutism.

[baby]

Usually a tech writer is also some sort of PM role that gets to chase developers and get them to explain what's in their head. Sometimes you have to have such a person on board.

[rsj_hn]

I once did an internship that involved chasing down senior devs and generating documentation for them (needed for FIPS certification). It was a great way to learn about the tech stack. Suffice it to say I didn't have any PM role at all.

[baby]

I'm not saying a technical writer should have a PM role, but it's a similar role

[innocentoldguy]

In my opinion, you shouldn't ask technical writers to manage projects anymore than you would ask engineers to. Both jobs are complex enough without adding an entirely different full-time job on top of the work.

[euroderf]

Get the brain dump when it's all still fresh in the head !

[q-big]

> and so that begs the question why not make twice as much working as a software developer and not have to sort out these types of messes?

You partly answered your own question: perhaps you pay the librarian/documentation writer too little? ;-)

Seriously: letting the documentation to be written by such a person won't be as much a cost-reducing measure, but instead mostly an approach to improve the documentation quality.

[namdnay]

My experience is that for internal documentation the time spent explaining things to a technical writer is bigger than the time spent writing the documentation

This isn’t the case for external documentation, that has to be more polished, needs sign offs and images and demos and stuff - tech writers can come in useful here

[pmoriarty]

Most developers just don't like writing docs, are too busy to write them, and aren't very good writers anyway.

So even on those rare occasions when they do actually document something, the documentation tends to be pretty bare-bones and not very readable.

Good technical writers are worth their weight in gold.

[bazmattaz]

Having worked with software engineers for the last 10years I can confirm, most don’t like documentation. At least 80% dont

[still_grokking]

Which is a funny statement as almost all devs like to have documentation.

[nmfisher]

If I'm simply consuming a library, I find most real-world documentation to be pretty superfluous. A full working example is usually enough to understand how things fit together.

If I'm working on a library, design docs and commented code is nice though.

[dividefuel]

It may take more time to explain it to a tech writer than it would for you to write it, but in most cases the final docs written by a tech writer will be much better.

[euroderf]

The tech writer's output will be a Force Multiplier.

[andrewflnr]

> I'm sure these are great technological answers

They're not, actually, as is obvious if you actually read the links. They're human process approaches.

[jrochkind1]

what's a butter robot? (I feel like i'm setting up a punchline for a joke somehow...)

[FridgeSeal]

It’s a reference to this: https://youtu.be/X7HmltUWXgs

[biztos]

Haha that’s awesome. I had figured it was just a typo for “better robot.”

[thegabriele]

Since the last episode we have also a lever robot

[mr_gibbins]

Sorry, should have been clearer - butter robot from Rick and Morty. An entity who has one menial job to do and that is the reason for their existence.

In this sense it was meant that the technological solution - auto documenter tools, etc - they're the butter robots. I was making the point that rather than just shim Yet Another Tool into the stack to do a single but important job (pass the butter / write the docs) perhaps give it to a human who will a) do a much better job and b) reduce the complexity of the stack.

Apologies for the confusion.

I'm surprised how this comment thread took off. Looks like there's plenty of support for AND against. I simply meant to make the point that for some problems humans do better than machines and it can be more efficient in the long term to look away from a tech solution to a human problem.

[daeminsong]

Thanks for asking this. Was too afraid to ask haha.

[spydum]

Probably a text to speech fail (edit: errr speech to text). Bot or robot == butter robot

[ebiester]

I’ve advocated for hiring a librarian but I haven’t ever been able to make the case successfully. So yes, I agree with you, but the “how” of structuring and the “who” are orthogonal.

This is about prioritizing the documentation you write.

[thatwasunusual]

> Why not employ a technical writer/documenter/whatever job title you like

Who would supply that person with the information required to write the documentation?

[innocentoldguy]

Subject matter experts, to the extent that the writer isn't one already.

In my opinion, companies should hire subject matter experts who can write rather than just someone with an English degree. I've fixed a lot of terrible documentation written by English majors with no engineering background.

[mrmrcoleman]

I came here for the butter robot.

[matai_kolila]

Er, the butter robot joke was a throwaway line about the exential crisis of a robot that carries butter, not a blueprint or metaphor about how to conduct software development, please for all that is holy don't try to read more into that than is there...

[FooBarWidget]

What's the difference between Diataxis and the Divio documentation framework? https://documentation.divio.com/

[Whitespace]

Seems like the Diataxis author came up with the framework while working at Divio: https://github.com/evildmp/diataxis-documentation-framework/...

[joegahona]

Indeed, they look identical, even down to the font used.

[k__]

Diataxis seems to be a fork of Divio.

But according to the network graph on GitHub, Diataxis seems to be more active, although both of them still receive updates.

[sidpatil]

From the GitHub page, it looks like Divio is actually a fork of Diátaxis.

divio/diataxis-documentation-framework is forked from evildmp/diataxis-documentation-framework, and evildmp is Daniele Procida, the creator of the latter repository and the maintainer of diataxis.fr.

[k__]

Thanks for the investigation!

[crazygringo]

Diataxis looks fantastic. That chart on the home page is absolute gold.

Thanks so much for the link, I wish I'd had that chart ten years ago!

[q7xvh97o2pDhNrh]

Whoa! I love a good 2x2, and the one on the Diataxis home page is great!

Adding a caption here for anyone on a screen-reader, before I give commentary on it:

  * X-axis: "serve our study" vs "serve our work"
  * Y-axis: "practical steps" vs "theoretical knowledge"
  * which gives 4 quadrants: how-to guides, tutorials, explanation, and reference

So I'm joining a new place recently, and it's another one of those "documentation-heavy" places where (of course) every new hire conducts the ceremonial ritual of updating the docs wherever they could use improvement. I really like having this ontology in my head now; I can see it being very useful.

Also, I wonder if the relative distributions of each one could tell you something about the team's health — or even just the kind of work the team does?

For example, between two teams who are both documentation-heavy, what does it means if one team's docbase is 80% tutorials, whereas the other team's is 80% reference guides? It would be fascinating if anyone's already given thought to relative metrics/heuristics like this.

[ebiester]

Almost every developer I've ever seen defaults to "explanation." Reference is there to the extent that it can be auto-generated, but most companies are relatively light on reference. Tutorials are pretty rare in smaller orgs - it rarely gets prioritized.

How-tos are an interesting case. I see a lot of informal how-tos in slack. However, how-tos also are the most likely to become stale because if they're needed often enough, they tend to become automated in part or whole. It is by its very nature transitory.

[c54]

Diataxis looks interesting thanks for the link

[capableweb]

Wow yeah, it puts into much better words than what I've been trying to get software engineers to do for a decade or more. Really awesome resource, thanks again kind parent :)

[googlryas]

The nice thing about this as well is that, unlike a technical framework, you can start implementing many of the ideas of this framework without any sign on from the rest of your group. And if it works, what will eventually happen is people will say "wow, capableweb rights such fantastic documentation, we should go to them and ask for their advice on how we can all write documentation that good"

[lliamander]

The diataxis seems quite interesting.

I see how it applies to documents which describe things as they are, but I'm curious how it would classify forward looking documents like technical designs, strategy and vision documents, roadmaps, and mission statements.

[throwaway290]

This does not help with outdated docs.