re: What did your onboarding documentation look like when you started your job? VIEW POST


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

code of conduct - report abuse