7 ms·

I love this topic! A couple of unconnected thoughts on it: I think one thing that's needed to establish a culture of written communication is getting rid of an

I love this topic! A couple of unconnected thoughts on 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.

hadsed 6y ago
I would say often times this does and should lie with the senior folks on a team. They're the ones who must be able to communicate well since their impact should be broader, perhaps even outside the team. And they should be scaling the team with their own knowledge and experience. I know it's a little different than what you're getting at but i think one person can do both.
wnevets 6y ago
>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. 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.
- aspaceman 6y ago
  If after “resolving” something you can’t actually write down what was accomplished, nothing was resolved. 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.
  - mandelbrotwurst 6y ago
    > If after “resolving” something you can’t actually write down what was accomplished, nothing was resolved. 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.
    - wnevets 6y ago
      >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.
    - cmwelsh 6y ago
      On my last team that would result in a JIRA ticket containing the details so approach Y was documented and the reasons behind it were recorded. Then the ticket is assigned to Person X and they go ahead with the work.
- mandelbrotwurst 6y ago
  I would go as far as to argue that this isn't just your being "bad with" async but rather an inherent drawback of async: namely that it requires way more context switching!
  - wilbo 6y ago
    Async requires more deliberate planning to avoid context more frequent switching. Time blocking is your friend and with asynchronous communication you have more freedom to time block. You can create a maker's schedule for yourself rather than the manager's schedule where your day is an endless string of meetings. 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.
karatestomp 6y ago
> 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. > 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).
- thu2111 6y ago
  Secretaries were and still are generic, unspecialised workers. I think the 'team librarian' idea assumes some level of technical knowledge. 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.
  - karatestomp 6y ago
    > Secretaries were and still are generic, unspecialised workers. 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.
L_Rahman 6y ago
Half of the reason I want to run my own company is build this culture and hire that role. The team librarian position is probably the single best value for money multiplier possible on team productivity and yet almost no one wants to invest in it. That's even before we get into second order effects of building new pathways into technology work.
- pc86 6y ago
  What do you mean by "building new pathways into technology work?"
gregmac 6y ago
> I'd love to experiment with hiring someone whose primary accountability is answering everyone else's questions, not generating output 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.
- deleted 6y ago
  [deleted]
maxwelljoslyn 6y ago
I would love to do this kind of work. Aside from a general passion for writing and editing, I enjoy describing problems, characterizing existing solutions' strengths and weaknesses, writing docs and user instructions, organizing information, etc. I'm a good enough developer to build useful tools and work with more senior engineers, and my favorite part of working in scientific research was being a force-multiplier and hindrance-destroyer so subject-matter experts could focus on using their skills. 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.
- aspaceman 6y ago
  Yeah same honestly. I don’t like producing a ton of code, but I’m good with tech and more complicated stuff like memory management. I think I could be very helpful just answering folks questions - I feel that’s mostly what I do anyways.
- kahmeal 6y ago
  This, to me, defines the heart of a true DevOps mindset. It's not easy to find this role defined as such, though, and you'll often find yourself fighting to carve it out of a more simplistic definition (i.e. automate stuff) at most organizations if you choose to pursue the path.
- randycupertino 6y ago
  I don't know if you've ever considered a position in pharma or biotech, but clinical research has a career like this called Clinical Trial Associate, and their entire job is to organize information, prepare instructions and documents for the research sites, organize and run the eTMF aka "Trial Master File" and other documentation tasks. Our CTAs start at 95k and make up to 125 for senior level. From there onwards you have a good career path of Clinical Trial Manager and leadership- might want to check into it.
  - maxwelljoslyn 6y ago
    I appreciate the tip. As it happens, my last full-time position was in clinical (computational linguistics) research. 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.
philwelch 6y ago
> 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. 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.
klenwell 6y ago
I love this topic, too. And this is so true: > 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.
- toast0 6y ago
  If you want to have ok documentation, making everyone do it, can work. If you want to have great documentation, it's hard. 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.
dcminter 6y ago
> 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. If I remember rightly, this is actually one of the core ideas in The Mythical Man Month.
- p_l 6y ago
  There is a librarian in the mythical man-month, and there are documentation writers and secretaries. All crucial to successful team - the librarian AFAIK was more about keeping stock of code (but would also fit with design docs), technical writers were crucial in transforming developer's ramblings into proper documentation, secretaries helped keep everything running smoothly, etc.
d23 6y ago
Another insidious motive for the avoidance of writing: keeping things off the record. 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.
- ChrisMarshallNY 6y ago
  I used to work with an IT person that Absolutely. Would. Not. Put. It. In. Writing. 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.
  - jacques_chester 6y ago
    The standard tactic in such situations is to send another email. "Hey Gerald, thanks for coming to see me. My understanding of your points was X, Y and Z. Let me know if that's wrong". 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.
    - brian_cunnie 6y ago
      I've written those types of emails you describe, Jacques: "My understanding is..." It's an excellent way to leave an audit trail.
msolujic 6y ago
> 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. 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/ https://9mcollab.com/ Full disclosure: I am advisor to young team behind it
- pc86 6y ago
  I'm not convinced the age of the team is relevant.
xtajv 6y ago
> 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 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.

hadsed 6y ago

I would say often times this does and should lie with the senior folks on a team. They're the ones who must be able to communicate well since their impact should be broader, perhaps even outside the team. And they should be scaling the team with their own knowledge and experience. I know it's a little different than what you're getting at but i think one person can do both.

wnevets 6y ago

>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. 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.

aspaceman 6y ago
If after “resolving” something you can’t actually write down what was accomplished, nothing was resolved. 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.
- mandelbrotwurst 6y ago
  > If after “resolving” something you can’t actually write down what was accomplished, nothing was resolved. 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.
  - wnevets 6y ago
    >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.
  - cmwelsh 6y ago
    On my last team that would result in a JIRA ticket containing the details so approach Y was documented and the reasons behind it were recorded. Then the ticket is assigned to Person X and they go ahead with the work.
mandelbrotwurst 6y ago
I would go as far as to argue that this isn't just your being "bad with" async but rather an inherent drawback of async: namely that it requires way more context switching!
- wilbo 6y ago
  Async requires more deliberate planning to avoid context more frequent switching. Time blocking is your friend and with asynchronous communication you have more freedom to time block. You can create a maker's schedule for yourself rather than the manager's schedule where your day is an endless string of meetings. 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.

karatestomp 6y ago

> 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. > 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).

thu2111 6y ago
Secretaries were and still are generic, unspecialised workers. I think the 'team librarian' idea assumes some level of technical knowledge. 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.
- karatestomp 6y ago
  > Secretaries were and still are generic, unspecialised workers. 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.

L_Rahman 6y ago

Half of the reason I want to run my own company is build this culture and hire that role. The team librarian position is probably the single best value for money multiplier possible on team productivity and yet almost no one wants to invest in it. That's even before we get into second order effects of building new pathways into technology work.

pc86 6y ago
What do you mean by "building new pathways into technology work?"

gregmac 6y ago

> I'd love to experiment with hiring someone whose primary accountability is answering everyone else's questions, not generating output 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.

deleted 6y ago
[deleted]

maxwelljoslyn 6y ago

I would love to do this kind of work. Aside from a general passion for writing and editing, I enjoy describing problems, characterizing existing solutions' strengths and weaknesses, writing docs and user instructions, organizing information, etc. I'm a good enough developer to build useful tools and work with more senior engineers, and my favorite part of working in scientific research was being a force-multiplier and hindrance-destroyer so subject-matter experts could focus on using their skills. 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.

aspaceman 6y ago
Yeah same honestly. I don’t like producing a ton of code, but I’m good with tech and more complicated stuff like memory management. I think I could be very helpful just answering folks questions - I feel that’s mostly what I do anyways.
kahmeal 6y ago
This, to me, defines the heart of a true DevOps mindset. It's not easy to find this role defined as such, though, and you'll often find yourself fighting to carve it out of a more simplistic definition (i.e. automate stuff) at most organizations if you choose to pursue the path.
randycupertino 6y ago
I don't know if you've ever considered a position in pharma or biotech, but clinical research has a career like this called Clinical Trial Associate, and their entire job is to organize information, prepare instructions and documents for the research sites, organize and run the eTMF aka "Trial Master File" and other documentation tasks. Our CTAs start at 95k and make up to 125 for senior level. From there onwards you have a good career path of Clinical Trial Manager and leadership- might want to check into it.
- maxwelljoslyn 6y ago
  I appreciate the tip. As it happens, my last full-time position was in clinical (computational linguistics) research. 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.

philwelch 6y ago

> 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. 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.

klenwell 6y ago

I love this topic, too. And this is so true: > 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.

toast0 6y ago
If you want to have ok documentation, making everyone do it, can work. If you want to have great documentation, it's hard. 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.

dcminter 6y ago

> 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. If I remember rightly, this is actually one of the core ideas in The Mythical Man Month.

p_l 6y ago
There is a librarian in the mythical man-month, and there are documentation writers and secretaries. All crucial to successful team - the librarian AFAIK was more about keeping stock of code (but would also fit with design docs), technical writers were crucial in transforming developer's ramblings into proper documentation, secretaries helped keep everything running smoothly, etc.

d23 6y ago

Another insidious motive for the avoidance of writing: keeping things off the record. 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.

ChrisMarshallNY 6y ago
I used to work with an IT person that Absolutely. Would. Not. Put. It. In. Writing. 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.
- jacques_chester 6y ago
  The standard tactic in such situations is to send another email. "Hey Gerald, thanks for coming to see me. My understanding of your points was X, Y and Z. Let me know if that's wrong". 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.
  - brian_cunnie 6y ago
    I've written those types of emails you describe, Jacques: "My understanding is..." It's an excellent way to leave an audit trail.

msolujic 6y ago

> 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. 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/ https://9mcollab.com/ Full disclosure: I am advisor to young team behind it

pc86 6y ago
I'm not convinced the age of the team is relevant.

xtajv 6y ago

> 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 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.