| My personal history with documentation from a programmer perspective is complicated. 20 something years ago I wrote a big system. It needed documentation so I hired a full time technical writer. He produced mountains of documentation, more than enough to satisfy the pickiest customer. And I'm pretty sure it was useless (beyond the sales process.) It described everything in detail, but lacked any sense of how things worked together, or how the program might be used to solve problems. He had a very shallow understanding of the customers and the domain. In other words it was all technical, no business or domain information. From this experience I learned that the best documenters are those who deeply understand the subject, and (critically) can impart that information to the user base. Good programmers with good communication, and good writing skills, are, well, rare. You've probably noticed this yourself online. If you are interested in say Grid stuff in CSS, you're unlikely to get value from the RFC and more likely to read some variety of blog posts on Grid until you find one that resonates. And it will resonate because the writer started where you are now, and shared how they got to where you want to be, and were able to write that journey down in a useful way. These days I write my own docs, and I consider docs to be part of the job. I don't release unless the docs are "done" (for some definition of done.) Apart from anything else, writing the docs helps me identify the clumsy parts of the program, so it's a feedback loop that causes me to improve the program. So, to answer your question, I think being a generalist "technical writer for hire" is hard. Ideally you would have a very deep understanding before writing, which implies some sort of specialisation. You'd also need a very close relationship with the creatives making the product. Doing that as an independent would be tricky. Personally, I wouldn't hire an external freelance documenter, but that's just me. We have hired internally, but I can't say we've had great success with it. Mostly because the creatives aren't interested in taking the prodigious amounts of time it would take to educate the newbie. Also because when we do take the time the result can be weak, which just makes the cycle worse. Probably the bigger need for us is internal documentation. I would hire someone to come in, and document "what people do all day". As a small business things have evolved, and lots of "end to end" business processes are "in someone's head". We've reached a size where retro-documenting our own business processes would be useful, and that's best done by an outsider. So maybe that's a better avenue to explore, although it's very niche. |
Interesting explanation about the trade-offs between an external software document expert vs someone hired internally. And I get that completely.
Very intriguing point about the internal documentation/day to day type stuff. I will look into that as I have not come across something like that as of yet. Could you nudge me in the right direction into what should I look for on the internet if someone was interested in the type of documentation you are referring to? What I'm understanding is that its the business analyst type documentation you are referring to?
Cheers.