21–30 of 53 posts
Internal documentation is nice, but really quite worthless for primarily three reasons: 1. At most one person is willing to create it 2. Nobody is willing to update it 3. Nobody is going to read it
Realistically, my advice is. Document as little as possible. Build processes into your tools so it can be tested and repeated. Documentation that can get outdated, will be outdated and even worse be wrong. And, for example APIs can be organized in a way that documentation can be automated, so its never wrong or outdated, by choosing to use API contract first, like Protobuf or implementing via OpenAPI specifications.…
Realistically, my advice is. Document as little as possible. Build processes into your tools so it can be tested and repeated. Documentation that can get outdated, will be outdated and even worse be wrong. And, for example APIs can be organized in a way that documentation can be automated, so its never wrong or outdated, by choosing to use API contract first, like Protobuf or implementing via OpenAPI specifications.…
What does "f.ex." mean here? Is it equivalent to "e.g."?
I also note all the issues, the things that people hate, when you talk about a sensitive topic and people grin like a serial killer because it's been pissing them off for months of years.
And after 2 or 3 months, when you can work on your own, go back to your notes and put everything down in the internal wiki (even the GitLab wiki if that's all you have), and improve the onboarding guide because it exists /s No, actually, it's your job to create this doc because it never exists.
As for what can be automated by scripts, you can do that, but a wiki is always nice because it tells people where those tools are, and how to use them, even it has a short description like "to build the application, 1. install this from winget, 2. and run this script." Automation is fun, but a guide or FAQ is great for what can't be automated.
Realistically, my advice is. Document as little as possible. Build processes into your tools so it can be tested and repeated. Documentation that can get outdated, will be outdated and even worse be wrong. And, for example APIs can be organized in a way that documentation can be automated, so its never wrong or outdated, by choosing to use API contract first, like Protobuf or implementing via OpenAPI specifications.…
What does "f.ex." mean here? Is it equivalent to "e.g."?
The core idea is to ask the person joining to keep a log of anytime something wasn't obvious, and they had to chase down an answer. IE they had to pair with someone to figure out a thing.
Then a month or so after they join, meet with them and go over the log. Doesn't mean the team fixes everything found, but it starts to build the picture of where someone joining has to spend most of their time, and can then have targeted fixes, process updates, etc. As long as the outcome isn't something vague like "improve docs" that no one will understand what the means or how to actually address it.
This also works for product UX discovery, for some types of products have every new joiner onboard as a customer would, and write down a friction log.
I’m a documentarian and this is one of my favorite topics. My go to is creating a wiki for the team. The wiki is organized into hubs. There is a hub for each team. There is a hub for each topic such as security, new employee onboarding, etc. There might be a hub for each bigger project.
A hub contains information about people, systems, and processes. For example, there might be a section for external services. Each of those gets a hub too.
Everything is hyperlinked. Search sucks in most wiki-like tools. Hierarchies are inadequate to capture the complexities of reality. Each page or hub is often relevant in multiple places and should be linked. Links should also be included to external resources whenever they will save time. This can include linking to concrete Slack conversations, Jira tickets, and pull requests.
During onboarding each new team member is asked to improve the onboarding documentation. Anyone can change any documentation. It’s not possible to keep documentation relevant if each team member does not use it.
Here is an article that I wrote about this a while back https://koliber.com/articles/engineering-documentation-best-...
I am really passionate about this and help companies do documentation well in engineering teams.
We have a high level wiki page about each application/micro service we support. Things like - resource locations - job schedules, purposes, inputs/outputs -FAQ's - known dependencies on other micro services, etc
We also have wiki pages for - onboarding - team norms and expectations (pr process, on-call duties, coding conventions, etc)
Inside each application's or micro service's repo the readme should have steps to - get the project running locally. - document feature flags - document conventions unique to that project - document how to trigger a release
Someone here said the code should be the source of truth and other documentation isn't needed. To me it's unclear what they mean by that exactly; I could get behind that if they are documenting via comments on functions/classes/etc. my org tends to not write much comments in the code so it's really hard to tell if the code does what it was intended to do or if there is a bug. What I love to see for "self documenting" code is tests. You write tests to either test for outcomes you expect or test outcomes that you don't expect, don't happen.
Before the first day.
First day.
First week.
First month.
The manager is expected to keep the new hire accountable in gettin g through their checklist.