π
- Are you a code-newbie and want to start coding?
- Are you a content writer and want to build your name?
- Do you like open-source and would like to give it a try?
- Or maybe you are somewhere in between or just want to be a better writer. Well, then we might make a good team.
βοΈ
I am the owner and co-maintainer of several projects with a few hundred repositories. Some projects might have several issues despite they are or could be a masterpiece. For reasons like:
It doesnβt matter how good software is because if the documentation is not good enough, people will not use it.
Even if for some reason they have to use it, without good
documentation, they wonβt use it effectively or the way youβd like them to.You using your code in 6 months. Code that was written 6 months ago is often indistinguishable from code that someone else has written today.
And many more similar issues.
π₯
This is where we could make a great team:
π¨
I can provide tools and content on many different topics. If you can write and organise the docs then you are the author of those docs which means you are the co-maintainer of the project. It doesn't necessarily have to be published or advertised. You will have all the rights to share it as yours having interesting material to write about. If you make reasonable progress - your work can be evaluated by professionals with detailed feedback which is very beneficial for the carrier and self-evaluation. Depending on time and progress more access and more popular projects can be introduced. π
π¨βπ
What is expected?
Keep a lighthearted friendly tone. Treat the reader as someone who doesn't have a lot of knowledge about the topic but is very interested. β€οΈ
Keep things brief πβπ¨
Use headings frequently. This breaks things up when reading and often it is good for linking to specific information.
Link to other places in the documentation often but only for additional information. Readers should not have to navigate through several pages to find information regarding one specific thing. Just inline the immediately relevant information and link off if they want to know more.
Use as many code snippets,
CLI
, etc. examples as possible. Show the reader what you meanGently introduce a guide before diving into technical details. This gives context and readers are more likely to stay engaged longer
It is always good to describe the functionality of the various files in the project.
Always use gender-neutral pronouns. A gender-neutral pronoun is a pronoun that does not associate a gender with the individual who is being discussed. ππΏ
For e.g. using 'they' instead of 'he/she'. β€οΈ
That's all! Friendly to code-newbies. Many things can be discussed to benefit everyone. ππΌ
https://developers.google.com/tech-writing
If you like to discuss or give it a try reach out:
digitalclouds@pm.me
admin@digitalclouds.dev
sall@digitalclouds.pro
Top comments (2)
Good summary. For any who'd like to write better docs, I'd recommend Google's tiny course(few hrs) on Technical Writing - developers.google.com/tech-writing
Cheers, for sharing. Awesome course.
Overall Google keeps surprising me on every aspect with recent changes.
Free challenge to earn a skill badge shouldn't be missed by developers.
cloud.google.com/training/badges