3 ms·

I think this is really just level 0 of what documentation is from everything I'm seeing. That sounds harsh! But what I mean additionally is that this is laying

I think this is really just level 0 of what documentation is from everything I'm seeing. That sounds harsh! But what I mean additionally is that this is laying the necessary and important groundwork to increase the legitimacy of documentation efforts. Being a backbone/level 0 I would caution you to keep in mind incentives to try and avoid perverse incentives Right now there are close to 0 incentives to either create or maintain documentation unless they're inherent in the team already. Or in the case of specific offerings business pressure (Example: API to external developers, but this also requires a business model that means lots of external developers that can't be interfaced with in a higher touch way). The perverse incentives I can think of immediately which are by no means exhaustive: 1. Increased visibility means increased visibility by management: A double edged sword where management must pick the right metrics to incentivize the production of good documentation. And on the other hand, increased visibility(internally and externally) empowers them to buy into the value produced by documentation efforts and help their teams build documentation habits. 2. This system necessarily increases # of tasks to be completed by a team. Over-subscribing to new task notifications leads to notification blindness or even worse notification dread. I personally love batched tasks that are relevant and important. I do not like things that interrupt focus or even worse interrupt my focus with things that are irrelevant at the current point in time. Nailing this is one of many things to be nailed in order to make the difference between being happy with a tool and feeling overwhelmed. 1 and 2 above can be generalized a bit. With the additional tooling you build on top of your "backbone" you are setting cultural, management, implementation, and usage standards and habits! So this leaves some core questions to inform the goals of this additional tooling to raise the profile of documentation. - What metrics should management focus on, how can they use this? Is it about keeping documentation updated as often as possible? Is it about producing documentation that the readers find informative? Is it about reducing errors in the documentation? Is it about X words per month? Is it about knowing which developers are the most likely best writers for a specific area of documentation? Does someone need help improving their documentation abilities? - Do documentation writers feel empowered rather than overloaded? Do they find value in the documentation that others are writing for them? (I.E. you notice them struggling implementing a feature, maybe there is relevant well written documentation to get them unstuck!) - And as readers of the documentation... it's not always just internal teams. What tasks are 3rd parties trying to solve with the documentation? Very granular documentation requires a "wide walk" of documentation. Very task focused documentation can mean missing additional information that allows the reader to generalize the task specific documentation to a broader use case. How are readers reading and engaging? I.E. They go to figure out how to do Task A and read section B on page 1, section A,C on page 3, section D on page 4. In this process they notice something slightly incorrect. Rather than just a thumbs down are they empowered to make changes or ask clarifying questions? Edit: And to keep this from becoming much longer than it already is :) I have one final important question. What is "bad" documentation and what is "good" documentation?

hahnbee 4y ago
Your point about incentivizing is very interesting. We mainly interviewed teams that were in our batch AKA early stage startups/small teams that didn't have much of a divide between management and developers - definitely a mistake on our part and we should definitely go back to interviewing larger teams. We knew that documentation is hard to maintain as changes are made and that a feature can be shipped without documentation having to be written/updated. We also agree that whatever our solution is - we need to be opinionated in terms of the "cultural, management, implementation, and usage standards and habits". I totally see where you're coming from about this being level 0 - at the very least we create visibility that something may or may not be updated. I guess the assumption we made was that a CI check would be enough (because the mentality is that you can't merge until you resolve everything) but there's definitely more incentives we can create. Analytics about documentation is something we've talked about, but it's definitely something we should talk about more seriously. > What is "bad" documentation and what is "good" documentation? There are definitely varying levels of granularity I can go into answering this question. As a baseline I can definitely say that bad documentation is documentation that is out-of-date - a series of instructions that are not the correct steps to get to the end goal that it claims will get for you. And good documentation is one in which it does allow you to get to your end goal. However, there are definitely layers to it - because I know for myself I'm very opinionated on how verbose, clear, or straight-to-the-point documentation is. Outside of just the content, there's also a lot that surrounds the structure of documentation. It's so clear that a problem exists here. We just have to figure out what the best solution looks like.
- ethanwillis 4y ago
  I like the answers in the last part. I literally had an interview today where I quoted a professor of mine from about a decade ago. He was very upset with me about some incorrect types in my javadoc comments and told me "The only thing worse than no documentation is wrong documentation!" :) For your answer on good documentation, that's a good general answer. As you say there are lots of layers to it. Some ideas just from my current viewpoint: - From my forays into foreign language learning I picked up the linguist's Stephen Krashen's research after learning about it from my language exchange partner. One of the main themes of his research is the idea of "Comprehensible Input"(CI). CI is the idea that you acquire knowledge via exposure to new language that is at a difficulty level where you understand most of what's being said. Then you acquire these new smaller pieces of knowledge via context. I would say this is most closely related to what you mean by structure of the documentation. Obviously with some overlap with the content itself. - There's also a stronger version of CI that adds an additional piece to this, the content must be of interest to the acquirer/learner. This property is I think the closest to what I think you mean in regards to content of documentation. In my opinion reaching the first goal, Comprehensible Input, where knowledge is able to be acquired efficiently is step 1. Resources of this type can be created much more easily as there is less subjectivity about the content's style itself rather than simply the pacing of the concepts introduced. The second part is obviously the hard part :) Maybe style text style transfer will start to get really good without the possibility of it influencing the former? [X] - Old video of Krashen explaining his central ideas https://www.youtube.com/watch?v=fnUc_W3xE1w https://www.youtube.com/watch?v=fnUc_W3xE1w P.S. I specifically mentioned text style transfer because I noticed your team had an offer of bringing in trusted technical writers. What would be a very good deal for both you, doc writers(at the client side), doc consumers, and 3rd party writers is the ability for their style to be automatically transferred into anyone's technical writing. 3rd party writers can license their fingerprinted style, Client side writers get a neat assist on quickly changing their writing style, and readers get a choice of voice they identify with.

hahnbee 4y ago

Your point about incentivizing is very interesting. We mainly interviewed teams that were in our batch AKA early stage startups/small teams that didn't have much of a divide between management and developers - definitely a mistake on our part and we should definitely go back to interviewing larger teams. We knew that documentation is hard to maintain as changes are made and that a feature can be shipped without documentation having to be written/updated. We also agree that whatever our solution is - we need to be opinionated in terms of the "cultural, management, implementation, and usage standards and habits". I totally see where you're coming from about this being level 0 - at the very least we create visibility that something may or may not be updated. I guess the assumption we made was that a CI check would be enough (because the mentality is that you can't merge until you resolve everything) but there's definitely more incentives we can create. Analytics about documentation is something we've talked about, but it's definitely something we should talk about more seriously. > What is "bad" documentation and what is "good" documentation? There are definitely varying levels of granularity I can go into answering this question. As a baseline I can definitely say that bad documentation is documentation that is out-of-date - a series of instructions that are not the correct steps to get to the end goal that it claims will get for you. And good documentation is one in which it does allow you to get to your end goal. However, there are definitely layers to it - because I know for myself I'm very opinionated on how verbose, clear, or straight-to-the-point documentation is. Outside of just the content, there's also a lot that surrounds the structure of documentation. It's so clear that a problem exists here. We just have to figure out what the best solution looks like.

ethanwillis 4y ago
I like the answers in the last part. I literally had an interview today where I quoted a professor of mine from about a decade ago. He was very upset with me about some incorrect types in my javadoc comments and told me "The only thing worse than no documentation is wrong documentation!" :) For your answer on good documentation, that's a good general answer. As you say there are lots of layers to it. Some ideas just from my current viewpoint: - From my forays into foreign language learning I picked up the linguist's Stephen Krashen's research after learning about it from my language exchange partner. One of the main themes of his research is the idea of "Comprehensible Input"(CI). CI is the idea that you acquire knowledge via exposure to new language that is at a difficulty level where you understand most of what's being said. Then you acquire these new smaller pieces of knowledge via context. I would say this is most closely related to what you mean by structure of the documentation. Obviously with some overlap with the content itself. - There's also a stronger version of CI that adds an additional piece to this, the content must be of interest to the acquirer/learner. This property is I think the closest to what I think you mean in regards to content of documentation. In my opinion reaching the first goal, Comprehensible Input, where knowledge is able to be acquired efficiently is step 1. Resources of this type can be created much more easily as there is less subjectivity about the content's style itself rather than simply the pacing of the concepts introduced. The second part is obviously the hard part :) Maybe style text style transfer will start to get really good without the possibility of it influencing the former? [X] - Old video of Krashen explaining his central ideas https://www.youtube.com/watch?v=fnUc_W3xE1w https://www.youtube.com/watch?v=fnUc_W3xE1w P.S. I specifically mentioned text style transfer because I noticed your team had an offer of bringing in trusted technical writers. What would be a very good deal for both you, doc writers(at the client side), doc consumers, and 3rd party writers is the ability for their style to be automatically transferred into anyone's technical writing. 3rd party writers can license their fingerprinted style, Client side writers get a neat assist on quickly changing their writing style, and readers get a choice of voice they identify with.