Add post about project onboarding #123
Conversation
AurelienRichez
force-pushed
the
post/onboarding
branch
from
a848d45
to
0d9ae8a
Compare
|
Thanks a lot for your review 👍 . I handled all your points |
| *The application might not need a full-time team.* A lot of systems don't need new features every week. Maybe the customer will ask for a new webpage, a bugfix, or an upgrade from time to time, but overall the project is in "maintenance mode". No one will be fully focused on that particular application most of the time. And a developer will have to do some kind of new onboarding every time to refresh their memory. | ||
| A developer might go away. At an individual level, life happens. Someone can get a better opportunity and leave the company, or they need to take a long sick leave, or they get hit by the https://en.wikipedia.org/wiki/Bus_factor[proverbial bus]. Then another person has to come in and fill the gap. | ||
|
|
||
| *A smooth onboarding means a happy productive developer.* This one is more arguable as it's harder to measure. It's similar to learning about a new product, say a shiny new database. If the "getting started" page's instructions work immediately then it inspires confidence. On the other hand, if the first command fails, and you have to search on Stackoverflow to get it working, it's irritating and does not convey a good image. The gist of it is that if you spend your day chasing information about how to start the app, by the time you get ready to actually code, you have exhausted your focus. |
There was a problem hiding this comment.
I would put this point as the first one. This one is common to all software teams onboarding people while the other two are not.
You say This one is more arguable as it's harder to measure. But this blogpost is not about it right? I would remove that sentence.
When a person is able to understand and start coding without too much effort, without having to bother and consume too much time from other people than that person is going to contribute more happily and quickly. I don't think this post should mention measuring it
|
|
||
| == Documentation is not a silver bullet | ||
|
|
||
| The first thing that comes to mind at this point is that we should write documentation. At the risk of sounding a bit provocative, documentation is a necessary evil. It should be our last resort, yet we often start with documentation. It is only one component of the equation, and there is often too much emphasis on it. |
There was a problem hiding this comment.
It should be our last resort I really don't agree with this sentence.
As you mentioned in the beginning the documentation should cover the code, the context and the domain.
I believe the context and a bit the domain have to be covered with documentation. The basic setup to be able to development the project as well (main stack and tool that have to be installed). Interaction between very separate components, for example, if appliable.
But for the rest, mostly the code, you can argue that making an effort of automating the documentation from the code is a valuable effort in the middle and long term because is something that is hard to keep up-to-date and it depends on the way the codebase evolves.
blog post written with the help of @sachgar and @Dedelweiss
I think it's a bit dense with the current blog engine so I'll propose another PR to add some margins on paragraphs.
I was also considering adding some images to makes the post less dense but I did not really find any good ideas, so feel free to suggests places where an illustration would make sense, or ways to trim the text a little bit.