On 5/25/20 11:51 AM, J William Piggott wrote: > > > On Mon, 25 May 2020, Michael Kerrisk via Libc-alpha wrote: > > ... >8 >> >>> We really need to engage with technical writers >>> and involve a broader set of industry skills in our projects. >> >> I want to add a note of caution here. It's great to have technical >> writers (and like good developers companies should be paying them), >> but they can't do the job on their own. A lot of developer input is >> still required. > > Another caution, many HR departments hire 'technical writers' that in > reality are copy editors, who's knowledge base is grammar/writing/language. > In my experience, they tend to make things a lot worse. Wordsmiths like > to use words, lots of words. They want to create novels. The complete > opposite of what technical writing should be. Agreed. We don't need copy editors. We need true technical writers that understand C and C++. Sadly, I've rarely met such people, and I agree with Michael, that I also find describing my code to be an illuminating part of design. Even though others don't share my interests, the linux man pages as a project shows there are enough of those people that the project can thrive and keep all the man pages well enough updated that they are more useful for API reference than the glibc manual. -- Cheers, Carlos.
