> what you need is a person who can answer questions while taking context into account.
A secretary. Teams need a secretary. Also to help wrangle the explosion of communication tools developers have to use these days.
I think a lot of inefficiency and wasted developer-brain-bandwidth on development teams could be solved with secretaries. But I've never seen it done. Probably part of the "with computers everyone can DIY their secretarial work, so now they must" and the shift (even farther) into secretaries being a status symbol more than anything else, and god knows we mustn't let developers have status (pay yes, status... oh hell no).
When I think of my own company, such a person would ideally be tasked with reading the user guides of the tools we use and quickly answering questions of the form "can we do this with it?", amongst other things.
This article is good but like others it focuses on the problem of getting people to write. I've found it's much harder to get people to read. The dirty secret of most workplaces is the massive disparities in reading speed that exist and the subtle tensions that can cause. It's something myself and my manager have both wrestled with, as we both read much faster than some of the other less technical people in the firm, and thus don't think much of dropping a six page memo on people or having long/complex discussions on Slack. Then they get frustrated at the implied expectation (sometimes that they put on themselves) to read it all.
Not at all! They'd often have to train in procedures and lingo for various occupations, so they wouldn't screw it up and could be maximally useful. Medical secretaries, for example, were once a pretty big occupation (I'm sure they still exist, but there were once lots of them) and they absolutely had to train in e.g. medicine names and greek and latin prefixes and meanings (beyond just mega- or whatever). Secretarial training, often with a focus on an in-demand field, used to be something community and junior colleges offered. "Some level of technical knowledge" is consistent with the role secretaries used to perform and the skills they used to have, in many cases, at least when "secretary" didn't mean "door and phone answerer". Acting as an advanced, human file search and process figurer-outer ("can we do this with it?") was also part of their role, coming with the territory of being responsible for filing (and often for producing the documents being filed in the first place).
If we have to go with "team librarian" for language/marketing reasons I'm still on-board, but "secretary" would be a fine label. That their often possessing significant domain knowledge not just as a side-effect of employment & experience but as part of their training is (perhaps?) no longer common knowledge is a sign of how far out of favor real professional-secretarial (that is, secretary to professionals) roles have fallen, I guess.
Writing requires you to put your name on your ideas. It promotes other pro-social traits, like being vulnerable. It's a lot harder to do negative politics if you're required to take your claims to paper. It's a lot harder to spread misinformation if you have other folks in the organization that can easily go look up your claims and fact check them.
Taking everything "offline" is a great way to bully, lie, cheat, and steal without fear of accountability. It hides incompetence. Weak leaders avoid writing lest they be exposed.
It was infuriating. I'd send him an email, spelling out a need or a project, and he'd walk three stories of stairs to come into my office to make his commitments.
For me, I believe in being held accountable.
You may have noticed that I take a rather unusual tack with my HN ID. I have full access and traceability in it. I have my personal brand attached to it.
That encourages me to be very careful about what I post.
I would love it if we were all more careful about what we post and say.
I have no control over others, so I make sure that I abide by my own standards.
Either they reply or don't. Either way you have established the paper trail. Possession might be nine tenths of the law, but the other ten tenths are coming to court with written evidence to defeat verbal evidence.
It's an excellent way to leave an audit trail.
Scott Adams once wrote a book: "The Way of the Weasel." It has some techniques in there that are remarkably familiar.
If anyone reading this is in a position to hire for a "technical writer/librarian/secretary/developer assistant," click my username and send me an email. We can try a short-term contract and see how it goes.
I've definitely applied to positions similar to what you've described, but as cold applications, they went nowhere. If I decide to return to regular W2 employment, I'll be sure to keep an eye out.
I pair people with questions with people with answers. I synthesise business requirements into usable tickets. I take ownership of cross-team tasks to make sure they don't get stuck. I digest a lot of information, and share the relevant bits with the relevant people. I make sure that important conversations happen, and that important things aren't forgotten.
In other words, I take care of all the details that would prevent the team from being focused and productive.
It's pretty fun. I am told to make things smoother, but left to decide how to do it.
It's an interesting idea, but I think the problem is that someone who can do this role (the intersection of technical competence and desire) is going to be exceedingly difficult to find or may not exist at all.
Someone that's going to be capable of providing useful answers to developer questions is likely to be a developer themselves, and almost certainly they're not going to stick around in that position for long. Part of being an effective "librarian" in this way is going to be knowing where to go to get a specific answer -- the existence of specific documentation, which group/team/person is responsible for which component, the levels of expertise of people on teams so you can immediately contact the lowest level person capable of answering, and eventually just knowing answers yourself. All of that comes with time, and if you have high turnover this isn't going to happen.
Also, someone that does the role poorly is going to be worse than nothing: unnecessarily bothering others for (maybe the wrong) information, providing incorrect answers, and/or making incomprehensible documentation. My guess is it's probably hard to judge someone's performance at this until they've been doing it for at least a couple weeks. If you also have high turnover, you will end up with people not suited for this role.
What if I'm just bad with the async nature of slack and/or email? If I had a nickel for everytime a long drawn out back and forth email thread that was resolved in less than two minutes with a face to face conversion and a white board I would have a shit load of nickels.
I’ve had a lot of 1on1s meant to “get us all on the same page” where a boss just blithers and blathers for an hour without communicating anything. The value in writing is working through the mistakes your brain makes during communication. Going to talking just makes it easier to ignore errors.
It's possible to "resolve" something / determine what to do next without writing anything down.
Often the ideal outcome is simply an agreement that Person X will move forward with approach Y.
Which you can write down if you so desire.
Slack and other instant messaging tools may make it feel like you need to be always on and responsive, but instant messaging is at odds with async.
If I remember rightly, this is actually one of the core ideas in The Mythical Man Month.
> I think one thing that's needed to establish a culture of written communication is getting rid of any cultural elements that allow people to use the avoidance of reading and writing as an expression of power.
I'm not in love of the idea of assigning a team librarian or scribe. I really want it to be part of the culture. Up to the executives. But if someone could demonstrate it works (and how it works), I could be persuaded.
One rule I try to impress on my team: you should be answering common questions whenever you can with a URL rather than a wall of text. That URL can link to a wall of text (or hopefully something a little better structured). Ideally in our wiki. That beats eight different people answering the question eight different ways. Or the same person answering it eight times in slightly different ways.
Very few people are going to be great at solving problems, great at expressing that in new code, great at maintaining existing code, great at debugging, great at testing, great at deployment, and great at documentation.
Specialization makes a lot of sense in many contexts, and writing documentation is one of them.
That's even before we get into second order effects of building new pathways into technology work.
I disagree that this would be a low/mid level position. In fact, I think it would be one of the highest ranking technical positions on a team, on the level of "library maintainer".
Documentation is useful because it allows the writer to transfer their own mental model to the reader. Like any data transfer, the fidelity of the reader's copy cannot exceed that of the writer's copy. So the writer ought to be the person on the team with the best mental model.
Unfortunately, newer developers tend to generate the most documentation by organic processes (in the form of notes and questions based on conversations with more experienced developers). In contrast, more experienced developers tend to silently figure things out without consulting another person.
Another issue is that developers with the best mental models tend to do a good job of assimilating that information into their global "context". This assimilation can make it difficult for these experienced developers to serialize their mental models into documentation, since the boundary between "mental model" and global "context" disappears.
For example - think about how you'd explain HTTP to a random stranger who has never programmed before. It's difficult to know where to start! Beyond that, it's hard to know what mathematical background to assume, how to topologically-sort topics s.t. you never use a term before it's introduced, how to prevent confusion, and everything else that makes teaching difficult.
In conclusion, I maintain that it really takes someone knowledgeable to write documentation which is: 1. scoped to a coherent audience and purpose 2. accurate across multiple layers of abstraction 3. resistant to documentation rot (without resorting to ambiguity)
Ideally, technical documentation would be written by the most knowledgeable person available.
This is perverse and contemptible in the 21st century. It reminds me of the line from the Simpsons movie: “I was elected to lead, not to read”. But it goes to show that any cultural change needs to come from the top in order to be effective.
What if the communication tool can help to sort out communication messinnes and produce knowlege base as team uses it. Like this one https://9mcollab.com/
Full disclosure: I am advisor to young team behind it
I think one thing that's needed to establish a culture of written communication is getting rid of any cultural elements that allow people to use the avoidance of reading and writing as an expression of power. You can frequently determine the balance of power between any two people in an organization by seeing which one has to read and prepare organized documents and presentations, and which one can simply speak and be spoken to. People want to paint pictures of themselves as being able to synthesize knowledge and ideas instantly, utter commands in real time and see them turned into action. In the other direction, they have no time for reading - you must request an audience with them and survive their real-time verbal sparring and probing questions to have your ideas received and considered.
My other musing on this is that I've always wondered if there would be value in teams establishing an internship or low/mid level position for a technical writer to serve as a team librarian. "Easy to search" is good, but "search" itself is not sufficient for many situations - what you need is a person who can answer questions while taking context into account. If I was running a technical team, I'd love to experiment with hiring someone whose primary accountability is answering everyone else's questions, not generating output. In the same way that a good dev needs to organize their workspace and build tools/scripts to be successful, this person will end up organizing the team's information to better accomplish their job.