alt Hacker NewsSounds really nice! Do you have an example of the concise, high quality communciation the Japanese team used? It'd be interesing to see what they focused on to make it so clear.
Replies
Not the person you asked here, but my guess is that it mostly has to do with the need for asynchronous communications. You can't just quickly ask the guy from Japan and expect an answer right away. That means the text needs to cover all questions.
I once worked in a job where each day of the week was covered by a different person. Meaning at the end of the day you had to leave everything in a state that another person could pick it up right away without much hassle. This was mostly done via emails and pieces of paper with text on it, but worked flawlessly.
And the only reason it did was because you couldn't just ask the guy from the day before a question. It all needed to be anwered by the work he left for you.
There are a few things.
- They didn't make assumptions about what the person reading would already know. Everything simple was explained, and was there were link to prior docs where complicated concepts were needed (e.g end of day cash consolidation in a store, because Japanese stores worked differently to US and Europe.) That made it really easy to read any document in isolation. We had a really good wiki that covered everything.
- The team insisted on keeping docs up to date, and deprecating old docs for things that weren't relevant any more. They kept things tidy. They didn't drop writing documentation when things got busy.
- They seemed to have spent quite a lot of effort organising things - tickets were always labelled and complete.
- They were dedicated to using consistent terminology everywhere. They had a glossary and they stuck to it, and that extended to the code that they wrote. Product docs, tech docs, and code all used the same language for the same thing. I think they avoided using similar terms for things too, especially where things could be ambiguous in translation from Japanese to English and vice versa.
To be honest, and with a decent amount of hindsight, I don't think anything was especially clever. It was just clear that the team put the effort in to doing the things most teams know they should be doing. I haven't worked there for a few years now but I bet they're having a lot of success with AI because that documentation would be a great source of context.