3 ms·

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 muc

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.

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.