how-to.md

📘 HOW TO USE THIS HANDBOOK

1. Our handbook aims to be extensive and keeping it relevant is an important part of everyone's job. The reasons for having a handbook are:
2. Reading is much faster than listening.
3. Reading is async, you don't have to interrupt someone or wait for them to become available.
4. Recruiting is easier if people can see what we stand for and how we operate.
5. Retention is better if people know what they are getting into before they join.
6. Onboarding is easier if you can find all relevant information spelled out.
7. Teamwork is easier if you can read how other parts of the company work.
8. Discussing changes is easier if you can read what the current process is.
9. Communicating change is easier if you can just point to a diff.
10. Everyone can contribute to it by proposing a change in the #io-handbook channel on Slack.
11. Documenting things in the handbook takes more time initially and it requires thinking. But it saves time over a longer period and it is essential to scale and adapt our organization. It is not unlike writing tests for your software.
12. Please follow these guidelines and remind others of them.
13. If you need to discuss with a team member for help please realize that probably the majority of the community also doesn't know, be sure to document the answer to radiate this information to the whole team. After the question is answered discuss where it should be documented and who will do it. You can remind other people of this by asking 'who will document this'?
14. When you discuss something in chat always try to link to a URL where relevant, for example the documentation you have a question about or the page that answered your question. You can remind other people of this by asking 'can you please link'?
15. To change a guideline or process, suggest an edit. After it is merged you can talk about it during the team call if applicable. You can remind other people of this by asking 'can you please send an edit proposal for the handbook'?
16. Communicate process changes by linking to the diff (a commit that shows the changes before and after). Do not change the process first, and then view the documentation as a lower priority task. Planning to do the documentation later inevitably leads to duplicate work communicating the change and to outdated documentation. You can remind other people of this by asking 'can you please update the handbook first?'.
17. When communicating something always include a link to the relevant (and up to date) part of the handbook instead of including the text in the email/chat/etc. You can remind other people of this by asking 'can you please link to the relevant part of the handbook?'.
18. If you copy content please remove it at the origin place and replace it with a link to the new content. Duplicate content leads to updating it in the wrong place, keep it DRY.

How to propose a change

Post a request in the #io-handbook channel on Slack, stating what you'd like to add / remove or change. You should add a link to the relevant paragraph or section.

For instance:

 I'd like to change the sentence that says "xyz" to "zyx" at this paragraph: http://.....

When adding new heading2 sections, prepend the title with a cool emoji.