A tech writer’s letter to software developers | Hacker News Reader

A tech writer’s letter to software developers

passo.uno

40 pointstheletterf20 comments

I've never seen a technical writer on a team in all my years in software. In wich types of software development are these likely to be found? My guess would be very large b2b sofware product teams ?

The places I've worked with tech writers have tended to be larger companies, yeah.

At startups, if any of the engineers has passable writing ability, they get tech writing on their list of job duties, in my experience. My previous company was a fintech startup, for example, and I wrote all the customer-facing API documentation and tutorials and code samples for their currency exchange service, in addition to implementing most of the service itself.

This is the way. Later on tech-savvy freelance writers are contracted to write more “professional” articles and documentation. It’s fluff but necessary to build the brand. IMHO the person who did the external API design should be able to convey the ideas behind their design in long-form as well. And vice versa, only let a person who can explain stuff well in writing design external APIs. Some companies call them DX’ers.

Author here: I spoke about how tech writers can assist API design here: https://passo.uno/posts/how-to-assist-api-design-as-a-techni...

In fact, I worked as the API designer for one of the APIs I also documented…

But aren't the "tech savvy freelancers" easily replaceable by ChatGPT nowadays? Since they are not adding more real meat there.

Define "tech savvy freelancer". Writers for content farms? Those are the technical writers the post describes.

And don’t you think it’d have been way more efficient to have a dedicated writer?

Maybe, but it wouldn't have been a slam dunk, because "have a dedicated writer" isn't a magic wand. I would have spent hours interviewing tech writer candidates instead of writing docs. I would still have spent a bunch of time putting information about the API into words for the benefit of the tech writer.

But the more important thing is, the product wasn't big enough or changing quickly enough to justify having a full-time tech writer on staff. The initial published version of the documentation was a few weeks of work to write and edit (spread out over a longer period since I was also doing other things, but a few weeks total). And after that, it only needed occasional updates when we changed something about the product or when a customer had a question that we realized indicated a gap in the documentation.

So we would probably have ended up hiring a contract tech writer. The writer wouldn't have been intimately familiar with the product. Which can sometimes be a good thing (since it means they have the perspective of a reader who is also not familiar with the product) but isn't necessarily great for efficiency.

And also, I enjoy writing! So it wasn't a burden for me at all, efficient or otherwise.

If you’re based in mainland Europe, that’s very likely, but things are starting to change.

I've always though that this was the role that eventually Evolves to Devrel.

Sometimes. Depends on the focus.

I've worked at a 10000 person company. We had a pool of ten tech writers for the entire company. So it tended to be either customer facing docs they were tasked with, where they'd collaborate with a team working on a new/overhaul product for a month or so, or else organisation of documents in internal wikis in times there wasn't one.

It pains me to see people being forced to change/adapt to support the most basics things (food, shelter and medical expenses for their family).

But the pragmatist in me clearly sees the writing (no pun) on the wall. Technical Writing is an area where ChatGPT and LLMs are going to excel. With tight integrations into Google Docs, Confluence, et al - the next generation of LLMs will be much better and ubiquitous.

That said, the Technical Writers of today can play a big role in using their skills towards Prompt Engineering.

Natural language is quickly becoming the programming language of the future. And this discipline excels at taking nuanced and highly technical topics, then distilling them into easily understood nuggets. Teaching the LLMs as much as possible with the shortest prompt: this is precisely what Prompt Engineering is all about. The task requires elegance and foresight (of how something will be interpret) that even LLMs don’t possess (yet).

In any case, I think their role is more important than ever before - just not in the traditional sense.

My team has been using ChatGPT for generating breakdowns of legacy code, including thousands of Fortran files for which there's no official documentation and the original developers are long retired. This is probably one of the best use cases I have seen so far of LLM aiding software development. With the overwhelming amount of legacy code running critical infrastructure in the US, I can see the enormous value LLMs can provide when tuned for documenting systems written in legacy languages like Fortran, Cobol and Delphi.

If you can provide more info about this, I'd be very interested. What sort of breakdown are you getting? Function names and descriptions of their behavior? Or is it more like the auto-generated reference documentation that you get from something like JavaDoc, where it's just a list of functions and argument names with no indication of what anything does?

Maybe once we figure out how to reliably prevent hallucination, LLMs can displace the most banal docs.

As far as long-form tutorials, information architecture, and concept doc? I'm not concerned about the future of technical writing for at least a couple of decades. LLMs write the kind of inflated, roundabout garden path sentences that I used to write in middle school to pad page counts. Tons of unnecessary adjectives and redundant sentences. It's hard to ask a question to an LLM and end up with a statement that doesn't contain a contradiction.

Maybe crappy technical writing will end up displaced. But great documentation is a lot more than just spewing words and facts on a page. You have to think about niche edge cases, API design, and higher levels of abstraction. Not to mention figure out how to actually use a new interface that, more often than not, doesn't match the original design spec in subtle ways.

Anyone who replaces technical writers with LLMs in the next couple of years will reap more than their share of developer discontent when the docs literally lie to them.

I am confident that prompt engineering is not a long term solution for anybody. The cost of creation is moving towards free. Anybody with an idea will increasingly be able to make whatever they want. The best one could do is to try to invest or build something that still has value, but I think Altman is right. Capitalism will collapse in a world where creation is near free.

Sounds a lot like the folks who claim that AI will replace music and literature. What makes you think that LLMs will make the jump from mediocre creation to high-level abstraction any time soon? I'm sure you can tell that I'm skeptical, but I am genuinely curious what indicators you're seeing in the AI landscape today that suggest this.

Those are very different use-cases.

Business vs. creative.

Everyone has access to music 24/7, yet people still spend hundreds of dollars to watch their favourite artists perform on stage. AI won’t change that. A few hit singles maybe - but it’s not taking over the creative industry.

Author here. The post doesn’t talk about that. I do have a couple posts that talk about LLMs and the future of tech writing though:

- https://passo.uno/hiring-tech-writers-chatgpt/ - https://passo.uno/openai-tech-writing-howto/

Reply on news.ycombinator.com