3 ms·
I started a job a few months ago and pretty much the first thing I did was improve the getting-started documentation, and the next thing was to improve the buil
by wpietri 11y ago
I started a job a few months ago and pretty much the first thing I did was improve the getting-started documentation, and the next thing was to improve the build process so there was less documentation needed. Worked for me.
Putting yourself in the mind of a reader is really hard. And documentation, which is necessarily duplicative, can easily become out of date. So yeah, I think novices are often the best people to write novice-targeted documentation, because they understand the reader's needs quite well.
Personally, though, I'd be a little embarrassed to assign a new arrival that if there were absolutely nothing. I think the process is a lot easier if they have some starting point for the docs, even if it's just some headings and bullet points. I'd also sit nearby and give them strict instructions to stop me at any point they were confused so that I could get them back on track. But I think it's a pretty good task on arrival.
- afarrell 11y ago> I think the process is a lot easier if they have some starting point for the docs, even if it's just some headings and bullet points. I'd also sit nearby and give them strict instructions to stop me at any point they were confused so that I could get them back on track. But I think it's a pretty good task on arrival. This is a good insight: the strategy does work if they have something to work through and a fallback if they are confused.
- cauterized 11y agoIt also depends on the developer. I'd consider it an appropriate task for a mid-level or senior dev who's already familiar with our stack, but not for a junior person or someone transitioning from another stack.
- peterwwillis 11y agoI did this, sort of, but had an interesting problem. Once i'd rewritten the onboarding documentation (because it was given to me as four or five different PDFs, which really isn't that useful, and doesn't tell you what you specifically will need to have set up), there was no place to put it; there were 3 wikis, none of which anyone really looked at other than for their own stuff. New hires wouldn't know where to look to find these onboarding docs and nobody else would know either. So it just floated around and new hires basically started with the PDF all over again.
- wpietri 11y agoIn our case, we just checked in the docs as part of the project. That's not always the best reader experience, but if they have the code, then they're sure to have the right version of the docs.