How can I encourage my team (and boss) to improve their documentation habits? | Hacker News Reader

How can I encourage my team (and boss) to improve their documentation habits?

4 pointsactionowl6 comments

I've worked for my current employer for a few years, both on-site, and remotely in the same timezone. This year I've been working for remotely with a 12 hour time difference.

It generally works out ok as I have about a 2-hour overlap with my team at the end of my day. However, a new problem has arisen that I don't know how to deal with and it's becoming more frequent.

I'll start my day and notice a JIRA story has been assigned to me. Often it's labeled high priority. The subject and description are vague. I'm lucky if it has acceptance criteria. Everyone is asleep, and I can't make any progress.

I can imagine the discussion: "Oh, that story we forgot about needs to get done soon, let's have him work on it tonight."

They forget that I wasn't in the room when they were talking about it, they forget that one person worked on it and didn't create any documentation. The story is so vague I may not even know what repo(s) it involves. I've had stories like this that have been written by other developers, the SCRUM master, and my boss.

Having worked with geographically distributed developers in the past, where you can't rely on tribal knowledge or hallway conversation I try to lead by example by adding notes and documentation everywhere. The feedback I get is that it is appreciated, and they'll say that they "should really start doing that too" but it has not caught on. The QA team has been the most appreciative as they're accustomed to writing bug reports and don't usually work with the developers directly.

I'm not sure how I can improve this situation. It makes me feel unproductive. Some days I am so discouraged that I have considering looking for a new job. There are plenty of other things I like about the company, and I'd prefer to stay and make things better, but I am out of ideas and looking for some new ones.

The template idea sounds promising, but the same could be achieved by just communicating the fact that you need more information when handed an issue you haven't been involved in discussing beforehand. Make this clear to whoever is your point of contact.

Explain to them (and this isn't a trick to get things to go your way) that this is a necessary step the team needs to take to both assist any future remote collaborators, to help with onboarding of ANY new people in the future (what-was-this-code-written-in-response-to kind of questions get answered much more easily this way) and generally promotes a culture of accountability, which is always good to have in a collaborative setting.

Then simply annoy whoever could give you information by mailing them or leaving them a couple of messages. This will over time make them more likely to provide all the required information.

Arrange your work so that you always have a backlog so that you don't have to work on that specific things every day, and you don't end up really blocked.

Thanks for the advice, I really appreciate it. You've made some great points here.

Can you propose a template with like the 5 minimum questions you need answered to get started:

1. What is wrong or what is missing?

2. What is the expected outcome?

3. What repo/module/screen?

4. Who is impacted, how and how often?

5. Anything else I should be aware of?

6. Optionally attach a relevant mail or screenshot

That is a good idea, I think JIRA has support for templates also. I often end up posting something like that on these vague stories but then have to wait until the next day to get an answer. Having this upfront sounds very helpful.

>I'll start my day and notice a JIRA story has been assigned to me. Often it's labeled high priority. The subject and description are vague. I'm lucky if it has acceptance criteria. Everyone is asleep, and I can't make any progress.

>I can imagine the discussion: "Oh, that story we forgot about needs to get done soon, let's have him work on it tonight."

This could be cleared up by a simple discussion about the nature of remote work and how you need more detail because nobody is around to answer questions.

Ironically, the way to handle communication break-downs is to communicate about them!

Have a conversation with the PM or whoever wrote the ticket. Tell them exactly what you wrote here. Problem solved.

Reply on news.ycombinator.com