I work in a six person team and I am the only remote team member. I have been in this job for almost a year and I find the remoteness to be an extremely difficult factor in domain knowledge acquisition, which feels like walking through deep snow. We have a Wiki and people post documentation pages but the problem is that they are poorly interwoven in content, i.e. they seldom reference one another when in fact they do build on top of one another, they are deeply set in a context to which the page itself does not point, IOW, they are hectic and not well structured. A very few are self contained and require no external context familiarity, mostly the ones I have written.

I have certain cognitive conditions, I avoid calling them shortcomings or disorders, which make me terribly incompatible with chaotic situations and data/sensory overloads. As a result, I have, over the years, developed my own methodologies how to learn new things and, more importantly, structurally organize the knowledge gained in the form of minimalistic and self-contained how-to, enumerated lists. When managing (which I don't do in my regular job) or mentoring somebody, I can say I am near machine perfect in outlining, knowledge transfer and documenting how to perform various processes in a similar fashion.

Unfortunately, my boss is not very supportive of my cognitive, learning and working styles. It feels as though he looks down on providing clear instructions to someone who needs it as a matter of either some darwinistic ideals of "fend for yourself" or not wanting to invest more man hours in clear process and domain knowledge documentation. Even when one team mate knows something solidly, it seems like I am expected to reinvent the wheel re-figuring it out myself or reverse engineering it. Don't get me wrong, I think reverse engineering is great but not if two people do it against the same functional area, it is reinventing the wheel and inefficient. Conversely, I am very eager to spare my team mates of unnecessary figuring out something I did already and provide them with a functional digest. When talking to him about it, directly or indirectly he explained that the team style is not "spoonfeeding" knowledge but encouraging members to acquire it on their own. I find that extremely inefficient and a borderline mask for "we don't document diligently". Several times I proposed things like I can fully document the development environment setup with all the components or prepare a simple git or maven cheatsheet for newcoming team members but he didn't have any appreciation for it. He is of the opinion that kind of knowledge should be a given and not necessitate team support. So my sentiment is that he expect us to individually find order in chaos and get things done. That may be easier for team members that sit with one another but it is really difficult being remote.

I would like to change this culture for the benefit of the team, myself, prospective new members, and the organization as a whole. I would like to raise the level of appreciation for providing clear process instructions in the form of enumerated lists. My boss tends to think I overcommunicate on the giving side and need being "spoonfed" (actually used that word) on the knowledge receiving end. I just really, really like structure and order, I am unable to function in chaos. I also think overcommunication is better than undercommunication. I think any organization should welcome that disposition as opposed to someone who keeps knowledge to himself even if they manipulate chaotic situations well. So my question is: what can I do to groom some appreciation for structured and specific knowledge sharing as opposed to simply expecting team members to know things and be familiar with the context?

  • 3
    Sorry, but over-communicative people are every bit as troublesome as under-communicative people. One is not better than the other. A big difference is that over-communicative people tend to be quite annoying to others. My first impression of what you wrote is what you see as lack of good documentation may be just your perception alone. If it was a problem for others then it seems like you'd have some allies in your quest. In my industry we document quite diligently and 75% of what we document is wasted effort. It becomes dated or is to time consuming for the benefit to reward ratio.
    – Dunk
    Jul 8, 2014 at 22:40
  • not really although it is related. this post is more specific since i have focused on a course of action (squeezing domain knowledge documentation from those who possess it), IOW, slowly convert chaos into order and go in in the future in a structured fashion.
    – amphibient
    Jul 9, 2014 at 19:07

4 Answers 4


It may seem reasonable to expect others to leap at the chance of a change to a "better" approach but my experience is that it is rarely successful. Another answer sensibly suggests setting a "good" example by adding well structured documentation to the WIKI. BUT, I think it would be a little naive to expect this to necessarily transform either the behaviour of the team or team leader. Firstly if the style is very different - e.g. longer, more detailed, more technical - than other documentation then it may NOT be perceived as an improvement: This is because while the current style and practice may be due to inability it may equally be because that is what works well for other team members.

When there is a clash of learning or cognitive styles the gap is even larger, and to take a up a slightly different issue, when I read the Question, I didn't warm to the tone. I felt I was being told the writer was determined they were right even though the rest of the team disagree. I wonder if that's exactly what the other team members feel? When I start in a new organisation, I believe the most important thing to do is to establish credibility quickly on their terms. In my role I am often invited to come and identify changes required and lead them. Even so, in the early stages it doesn't matter if I disagree with the current practice, I am less likely to be listened to in terms of change until I've a) had some success and b) followed the existing rules (or at least some of them). If I can't achieve success within the framework that exists, I may not gain permission to influence change. In truth it doesn't matter if you are right and they are wrong (or the other way round) people choose whether to accept change. The closing question was "what can I do to groom some appreciation for structured and specific knowledge sharing as opposed to simply expecting team members to know things and be familiar with the context?" My answer would be, get better at playing their game with their rules first, use better practice in a way that IS acceptable as opportunity arises, have some success and allow others to choose if they want to follow your better practice once you are established.

And finally, it's worth seriously considering how the current process works, ask honest, open questions about how the team benefit from the current process and the answers may reveal something useful - and it has the added benefit of showing that one is open to the ideas and experience of others.


Don't give up, this problem is neither new, nor is it uncommon.


There are countless reasons why managers expect you to not require time to formally structure knowledge to share, some of this reasons are flawed logic all the way to intentionally undermining.

Common Misconceptions by Managers

  • Time spent structuring knowledge is time that could be used on actual work lost
  • Time spent structuring knowledge is lost as this knowledge changes to rapidly
  • My "experts" should already know this stuff without documentation
  • My team should be able to transfer knowledge without the time investment of structured documentation

This list honestly could go on for hours, but of coarse five seconds of research shows studies proving any of these points wrong, but no study will convince a manager to go against their gut. (nor will this thread)

Improvement through example

Perhaps you can't get your boss to bite embracing structured knowledge, but that doesn't mean you can't do it. Especially as a remote person he can't constantly monitor you.

Perhaps I'm not my manager's favorite person but in these sort of matters I go with "do it anyway" as I work through the problem I add relevant unit tests, documentation, logging, monitoring, and code clean up. All of these things are stuff we as a dev team have requested additional time for and were denied.

We all know proper documentation saves more time in the long run, and in the case of software tests and logging are also excellent ways to save yourself painful debugging time.

This has caused the occasion deadline to go long for me and there are times it's created a certain amount of tension in my office between myself and my boss. It's also resulted in countless times I've saved us hours thanks to a simple test, log, or documentation piece.

In time my boss has given me a lot more time and freedom to get these things done, even some dedicated time. He's still not really happy about it, but he does respect what I do, and even made it clear in many cases I was right and what I've done has "save their bacon"

To be entirely honest early in this process I feared I'd get fired for the occasional deadline slip or for insubordination. Ultimately what I've done has been so important to the process now we couldn't go back. (people would quit) I also decided early on, I'd rather get fired trying to make things better than keeping my head low and accepting a crappy situation.

Good luck, don't get confrontational if you can help it, but do what you must to make yourself and your team as effective as possible.

  • double-like for the list of "Common Misconceptions by Managers" ... i so can relate to it
    – amphibient
    Jul 8, 2014 at 21:30

You need to escalate to your manager, assuming that you have one.

You need to lay out to the manager the cost of inadequate documentation and the cost to the company's bottom line of everyone trying to figure everything from scratch on their own.

Your team is probably blowing scads of time that could have been spent in other pursuits. Never mind that without adequate documentation, everybody will have a hard time remembering what they did six months ago. Some will have to resort to making sense out of their own code and in a few cases, they will fail at it. If the code is poorly architected and poorly written, then good documentation becomes imperative.

However, something strange and inconsistent is happening if the documentation is excellent and the code is poorly architected and poorly written.

Unfortunately, it makes much more sense that well written documentation goes in sync with well architected and well written code.

Yeah, escalate to the manager because you are running into resistance from the team including the team leader but keep in mind that the documentation mitigates to an extent the pain created by poorly architected and poorly written code but it does not cure it.

  • the person i refer to as "boss" in the OP is actually my immediate manager
    – amphibient
    Jul 8, 2014 at 21:32
  • @amphibient I don't get it. How does the team leader and you fit in the hierarchy? Is there anyone above your "immediate manager"? Jul 8, 2014 at 22:45
  • no one ever mentioned a "team leader". he is my manager/boss.
    – amphibient
    Jul 9, 2014 at 3:15
  • Is there anyone that your boss reports to? Jul 9, 2014 at 3:33
  • 1
    dude, i am not going over my boss's head. are you kidding?
    – amphibient
    Jul 9, 2014 at 3:53

I may be mistaken, but reading through your question, I see a lot of proposals - a lot of talking. I don't see anywhere where you actually did something.

If you think that your internal documentation should be different/better, then make some. Then you have a concrete example to show others so that they can see what you mean, and evaluate how that documentation is better/clearer.

It's rare that people appreciate sentiments or concepts. They appreciate things; things that make their lives easier.

  • the question was how to extract domain knowledge from team mates in a structured and easy fashion. it is an initiative in itself. your "answer" provides nothing of value and is more suitable to be a comment...
    – amphibient
    Jul 9, 2014 at 22:00
  • @amphibient - How do you figure? You want your team to provide domain knowledge in a structured and easy fashion. Start by showing what you think a structured and easy fashion is in concrete terms so that they can better give you what you want.
    – Telastyn
    Jul 9, 2014 at 22:07
  • "A very few are self contained and require no external context familiarity, mostly the ones I have written."
    – amphibient
    Jul 9, 2014 at 22:12
  • "Several times I proposed things like I can fully document the development environment setup with all the components or prepare a simple git or maven cheatsheet for newcoming team members but he didn't have any appreciation for it. He is of the opinion that kind of knowledge should be a given and not necessitate team support."
    – amphibient
    Jul 9, 2014 at 22:12
  • @amphibient - okay, you wrote documentation and you proposed making more. Did you tie them together though? Did you sell your approach to documentation by looking at it and selling the benefits it would provide the company (not just you)? Why didn't people buy it?
    – Telastyn
    Jul 9, 2014 at 23:24

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .