4 ms·

Ours is here: about.gitlab.com/handbook - it's open source: gitlab.com/gitlab-com/www-gitlab-com/ My tips: 1. Maintain a clear single source of truth 2. Make

Ours is here: about.gitlab.com/handbook - it's open source: gitlab.com/gitlab-com/www-gitlab-com/ My tips: 1. Maintain a clear single source of truth 2. Make sure everyone can contribute to it. We do this by requiring at least to edits to the handbook during onboarding 3. Embrace it as an organisation: if not everyone is committed to it, it's hard to maintain it as truth 4. Constantly iterate and improve it. Structure is highly dependent on the content.

mathatoms 8y ago
I think point 2 is really important. I've worked with a lot of new hires, especially college interns, and some of them are deathly afraid of coming in on the first day and messing something up. I always put together a getting started page on whatever wiki we happen to be using that details how to get the development environment up and running on the first day. Since the development environment changes as our code matures (new libraries to build against, new repos to check out, etc) following the wiki never seems to just work for someone unfamiliar with the dev environment and they encounter problems or just have questions. Whenever someone has a problem or a question the solution should be documented in the wiki, so we have the new hire update the getting started wiki as they go along. This gets them a little more comfortable making changes (since they see the whole building didn't burn to the ground after making a wiki update) and gets them in the process of documenting any problems or questions.
clebio 8y ago
Curious whether you really mean _everyone_ -- including non-technical roles like Sales? I notice that for instance Sales seems reasonably well document [1] so, maybe so? [1]: https://about.gitlab.com/handbook/resellers/ https://about.gitlab.com/handbook/resellers/
- jobvandervoort 8y ago
  Yes, everyone == every single person employed by GitLab Inc.
ggregoire 8y ago
wow that's great. How do non technical people can update it? Do you teach them Git?
- jobvandervoort 8y ago
  Exactly. Or at least teach them to use GitLab, which is a good motivator to make the product easy to use.

mathatoms 8y ago

I think point 2 is really important. I've worked with a lot of new hires, especially college interns, and some of them are deathly afraid of coming in on the first day and messing something up. I always put together a getting started page on whatever wiki we happen to be using that details how to get the development environment up and running on the first day. Since the development environment changes as our code matures (new libraries to build against, new repos to check out, etc) following the wiki never seems to just work for someone unfamiliar with the dev environment and they encounter problems or just have questions. Whenever someone has a problem or a question the solution should be documented in the wiki, so we have the new hire update the getting started wiki as they go along. This gets them a little more comfortable making changes (since they see the whole building didn't burn to the ground after making a wiki update) and gets them in the process of documenting any problems or questions.

clebio 8y ago

Curious whether you really mean _everyone_ -- including non-technical roles like Sales? I notice that for instance Sales seems reasonably well document [1] so, maybe so? [1]: https://about.gitlab.com/handbook/resellers/ https://about.gitlab.com/handbook/resellers/

jobvandervoort 8y ago
Yes, everyone == every single person employed by GitLab Inc.

ggregoire 8y ago

wow that's great. How do non technical people can update it? Do you teach them Git?

jobvandervoort 8y ago
Exactly. Or at least teach them to use GitLab, which is a good motivator to make the product easy to use.