I'd love to know what onboarding materials were provided to you when you started your job.
What does good documentation look like for getting started with a codebase? For getting started building features?
It's common to receive documentation around getting your dev environment set up, and the basics of building/running/testing/deploying the software you'll be working on.
But has anyone been provided with anything further? I'm imagining some "this is how we build stuff" documentation, detailing preferred patterns, or giving an introduction to the codebase, useful shared components, etc.
How about "this is how we work" documentation - i.e. who approves PRs, how to ask for review, how long is acceptable to wait, how work gets assigned, etc. Has anyone ever been issued useful documentation around process?
If so, I'd love to hear
What the project was (language, framework, basic function)
What general areas the documentation covered
How useful the documentation was
If you have been involved in maintaining the documentation, how you have found that.
Top comments (3)
In one of our project we went through code directly and that was annoying there was no on boarding documentation for us.
We decided to create the documentation for our team to get started with project.
But we don't have 'This is how we work' documentation.
I personally thing it's a really good idea to have 'this is how we work' documentation.
Thank you for sharing this!
I'll share some of my own examples from past jobs.
Company A:
Node, React, Ruby, Rails, AWS stack. There was a frontend app and many smaller microservices, all deployed on AWS.
The written documentation usually lived in the project repos, and covered the basics - how to run, test and deploy the code, plus a brief summary of the function of the service in the overall architecture. Also, a list of required environment variables and their uses. Occasionally, if there was something worth drawing developers' attention to, such as where some important logic was handled, this might be included. There was little info that would easily go out-of-date so in general the READMEs were up-to-date and were included in code review, i.e. we'd get reminded to update the README if necessary.
I also received onboarding documentation around how to set up my machine, which was less up-to-date. Some of the tools I installed we never used, and the workflow doc turned out to not really represent how we worked (it portrayed an idealised way of working, what was not how we practiced in reality. Not that our way of working was worse, it was adapted for our team, but just saying that the workflow doc left me confused initially as I attempted to follow it, to no avail.)
The documentation was useful, often it included details that I referred to not only during onboarding but whenever I worked with the project. What I perhaps could have used was something written explaining terms and jargons used in the problem domain, also the app itself had no documentation at the time so I didn't understand how many of its features were supposed to work (as they were only partially developed).