DEV Community

Cover image for Are you a writer?
Sall for Digital Clouds

Posted on • Updated on

Are you a writer?

πŸ“œ

  • 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:

  1. It doesn’t matter how good software is because if the documentation is not good enough, people will not use it.

  2. 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.

  3. 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 mean

  • Gently 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)

Collapse
 
gitcommitshow profile image
gitcommitshow • Edited

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

Collapse
 
sso profile image
Sall

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