6 ms·

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

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

ghaff 4y ago
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.
CrypticShift 4y ago
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.
- euroderf 4y ago
  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.
- beckingz 4y ago
  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.
  - CrypticShift 4y ago
    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).
  - mycall 4y ago
    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
  - spencerchubb 4y ago
    '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 4y ago
      >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.
    - thepawn1 4y ago
      The age old issue. There's oodles of data at how people don't keep doing it because it's toil to them.
- bloaf 4y ago
  You need to 1) Link to the documentation in your tools 2) Ensure everyone has edit access to the linked documents
spoils19 4y ago
> 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.
Viliam1234 4y ago
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.
- brendank310 4y ago
  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.
- stevesimmons 4y ago
  > 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 4y ago
    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.
gopher_space 4y ago
> 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.
q-big 4y ago
> 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.
baby 4y ago
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.
- euroderf 4y ago
  Get the brain dump when it's all still fresh in the head !
- rsj_hn 4y ago
  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 4y ago
    I'm not saying a technical writer should have a PM role, but it's a similar role
- innocentoldguy 4y ago
  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.
innocentoldguy 4y ago
> 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 4y ago
  > 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 4y ago
    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.

ghaff 4y ago

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.

CrypticShift 4y ago

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.

euroderf 4y ago
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.
beckingz 4y ago
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.
- CrypticShift 4y ago
  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).
- mycall 4y ago
  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
- spencerchubb 4y ago
  '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 4y ago
    >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.
  - thepawn1 4y ago
    The age old issue. There's oodles of data at how people don't keep doing it because it's toil to them.
bloaf 4y ago
You need to 1) Link to the documentation in your tools 2) Ensure everyone has edit access to the linked documents

spoils19 4y ago

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

Viliam1234 4y ago

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.

brendank310 4y ago
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.
stevesimmons 4y ago
> 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 4y ago
  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.

gopher_space 4y ago

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

q-big 4y ago

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

baby 4y ago

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.

euroderf 4y ago
Get the brain dump when it's all still fresh in the head !
rsj_hn 4y ago
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 4y ago
  I'm not saying a technical writer should have a PM role, but it's a similar role
innocentoldguy 4y ago
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.

innocentoldguy 4y ago

> 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 4y ago
> 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 4y ago
  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.