I am considering mentoring tech writers to contribute docs to open source projects, but I want to make sure I don't create additional work for open source maintainers. Can you help me understand:
- If a tech writer wants to contribute docs your open source project, what would you want them to focus on?
- How much effort would it take on your part to help them make effective contributions?
- What would make you nervous about their contributions?
Top comments (13)
We created a blog post highlighting step by step guides to editing the docs. We made the process as low friction as possible by using githubs wiki support to manage our docs. This way anyone can just edit them directly.
As a result we got a few contributions but nothing serious.
That's very thoughtful! Can you share the link to the blog post?
Sure this is it: codenameone.com/blog/tip-edit-docs...
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.
i really want to contribute to open source fo real
Hi, maybe the tool I created will help you do that justcontribute.netlify.app
Good luck!
This is neat! Thank you!!
Do it!
What programming language do you use?
nodejs bro but still at junior level
My advice would be to follow this guide:
github.com/firstcontributions/firs...
Once you have successfully done your first contribution, start to look through Github for issues tagged with
good first issueHere's a link that might be useful to you:
github.com/MunGell/awesome-for-beg...
thank you bro will take a look
Normally this detail is given in the issue itself and a guide on how to best contribute can be found in a CONTRIBUTING.md file inside the repository. I hope this helps