What level/definition of tech writer are you thinking about? As in, how deep will/can they explore the technology?
One of the most important, and also difficult part, is to communicate the idea and flow behind a piece of technology. How it was intended to be used by the creators. For the creators this is extremely difficult to convey, because it all feels to natural to them. It is like when you write a 2 page document, you read it 20 times, and everything seems ok. But when you let somebody else read it, they find an typo within the first 10 sentences. This is also the case with trying to explain your tech's ideas when you developed it. I think that's something that needs the primary focus. Because when you understand the idea behind the tech, a whole bunch of the details well feel more natural.
The thing that would make people the most nervous is that the tech writer probably needs a lot of Q&A with the maintainers. So the maintainers will thing it will cost them a lot of time, which they could spend on making their tech better. Not realizing that explaining the tech to the writer can make the tech more approachable. It really is a case of investing.
Lets face it, the average and vast majority of developers are not great in documentation. This is really a different skill. In case of an open source project, part of the task of a tech writer is to convince the maintainers that they need to invest time with the writer in order to get results.
Thanks for the response! I couldn't agree more. I find myself telling new tech writers looking to build their portfolios to "contribute to open source projects", but I am aware of how much additional burden it can place on the maintainers. Thanks for validating my concerns!
I am also considering arranging a Technical Writing challenge for Hacktoberfest, where open source projects open smaller, modular docs issues that tech writers can then work on. I need to think through this.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
What level/definition of tech writer are you thinking about? As in, how deep will/can they explore the technology?
One of the most important, and also difficult part, is to communicate the idea and flow behind a piece of technology. How it was intended to be used by the creators. For the creators this is extremely difficult to convey, because it all feels to natural to them. It is like when you write a 2 page document, you read it 20 times, and everything seems ok. But when you let somebody else read it, they find an typo within the first 10 sentences. This is also the case with trying to explain your tech's ideas when you developed it. I think that's something that needs the primary focus. Because when you understand the idea behind the tech, a whole bunch of the details well feel more natural.
The thing that would make people the most nervous is that the tech writer probably needs a lot of Q&A with the maintainers. So the maintainers will thing it will cost them a lot of time, which they could spend on making their tech better. Not realizing that explaining the tech to the writer can make the tech more approachable. It really is a case of investing.
Lets face it, the average and vast majority of developers are not great in documentation. This is really a different skill. In case of an open source project, part of the task of a tech writer is to convince the maintainers that they need to invest time with the writer in order to get results.
Thanks for the response! I couldn't agree more. I find myself telling new tech writers looking to build their portfolios to "contribute to open source projects", but I am aware of how much additional burden it can place on the maintainers. Thanks for validating my concerns!
I am also considering arranging a Technical Writing challenge for Hacktoberfest, where open source projects open smaller, modular docs issues that tech writers can then work on. I need to think through this.