4 ms·

Here's my perspective. I've been a technical writer (TW) for ~10 years. 3 at an IoT startup, 7 at Google. > The strengths of this process are also its weakness

Here's my perspective. I've been a technical writer (TW) for ~10 years. 3 at an IoT startup, 7 at Google. > The strengths of this process are also its weaknesses. A developer is, by definition, someone who spends the majority of their time doing development, which is to say writing code. Updating the documentation becomes a task that must be completed so that the code one has written can get committed so that one can move on to the next project and write some more code. I may be misinterpreting, but I get the sense that the author feels that there is some kind of more optimal way to split up docs duties. IMO there is not. At least, not for reference docs. As the author said, the people implementing the code are in the best position to keep the reference information up-to-date. If I grokked the rest of the article correctly, the author is essentially saying that the engineers have trouble writing and maintaining the other main types of docs [1] --- guides, tutorials, and overviews (explanations). It also sounds like they are having a "too many cooks in the kitchen" problem with pushing through changes to the other docs. I have a simple answer to that: hire some strong technical writers and make it clear to everyone that the TWs are Responsible and Accountable [2] for those docs. Also, make it explicit that the engineers are a Consulted role when it comes to guides / tutorials / overviews. Writing these types of docs is hard, specialized work. As the author said, the engineers have lots of other priorities. Of course, it's a bit self-serving for a TW to say "the solution is to hire TWs" but I get the sense that people don't realize that the easiest way to get good guides / tutorials / overviews is to hire people who have thought long and hard about those specialized tasks. If you want a good database, you don't expect your TWs to do the job. You get a database engineer. If you want good tutorials / guides / overviews, you likewise shouldn't expect your database engineer to do the job. You get TWs. [1] https://diataxis.fr https://diataxis.fr [2] https://en.m.wikipedia.org/wiki/Responsibility_assignment_matrix https://en.m.wikipedia.org/wiki/Responsibility_assignment_ma...

btilly 3y ago
Just curious. Where do you think that an open source project like PostgreSQL gets a budget to hire anyone? Let alone to dictate a new line of authority to the volunteers who are already maintaining it? And don't forget that there are valuable volunteers who are likely to go elsewhere if too many new rules are added that they don't want to live with.
- kaycebasques 3y ago
  Open Web Docs is a potential model to draw inspiration from regarding funding: https://openwebdocs.org https://openwebdocs.org Presumably, PostgreSQL has leaders who are responsible for steering the ship. If the project is going to succeed long-term, those leaders have to find ways to keep their contributors happy while also creating an organizational structure that leads to good docs. Easier said than done, I know, but it really is as simple as that. Sorry if any of my comments came off naive or obtuse when it comes to open source dynamics. But the reality is that you need good docs, and I'm just trying to give an honest assessment from my experience of the conditions that lead to good docs.
  - btilly 3y ago
    Sorry if any of my comments came off naive or obtuse when it comes to open source dynamics. If you want that apology to be meaningful, you should learn something. When you're talking about a highly successful open source project that has been going for more than 3 decades, it is beyond ludicrous for you to say, "If the project is going to succeed long-term..." It already has succeeded long-term. And you would be better off figuring out why it works rather than lecturing about how it must work. When you talk about "a potential model to draw from" for funding, please note that I've been involved with open source for about a quarter of a century. I've seen a LOT of funding models attempted. Mostly they run into one big problem. And that problem is that adding funding creates bruised egos because people say, "Why is he getting paid when I'm not?" The one funding model that DOESN'T have this problem is when a company decides to pay its employees to work on features that it wants in the project. Now there are no bruised egos - the money comes from the company and it is clear why one person gets paid while another does not. There are still challenges with this model - employees are under pressure to get their contributions accepted whether or not the project likes them - but we've learned how to navigate those. But now we're left back where we started. Companies who hire core developers don't generally need comprehensive documentation - they build internal documentation straight for their use case. So comprehensive external documentation is hard to find. Sometimes you'll wind up with things like an excellent introductory tutorial like https://docs.python.org/3/tutorial/ https://docs.python.org/3/tutorial/. Usually, you don't. And generally it is hard to simply pay someone to take care of it for you.
kaycebasques 3y ago
Just re-read the last two paragraphs from Haas. I have a couple further comments / questions. Quote from Haas: > But if on the other hand I propose some change to documentation that has existed for a long time, or some kind of structural change, there's a lot more room for disagreement. Because the change isn't strictly mechanical, the right answer is a lot more subjective. And because it's a change to existing content rather than the addition of new content, many more people will be familiar with it and have opinions on how it ought to be changed, if at all. Consequently, even when some developer does take time away from writing code to try to make some larger change to the documentation, it's often an uphill battle to get anything done, and people typically have to be content with small improvements. Honest question: do PostgreSQL engineering decisions have the same dynamics as what's described here for docs decisions? If not, what is different about engineering decisions versus docs decisions? Is it just that engineering decisions can be literally benchmarked whereas docs decisions do not seem benchmark-able? Are there any other potential explanations for different dynamics between eng and docs? If it does indeed just boil down to "docs are not benchmarkable" then I would suggest otherwise. You can create docs benchmarks. They won't have the rigor of engineering benchmarks but they at least establish some notion of docs quality and facilitate more targeted discussions during docs reviews. E.g. when there's a disagreement between an author and reviewer the author can say, "what docs benchmarks am I not following here?" The power of that kind of interaction is that you often do realize that the docs benchmarks are incomplete and some new dimension needs to be added to them. Or do the PostgreSQL contributor docs already have some guidelines along the lines of a "content quality checklist" and it's still not working? A rigorous effort to survey the PostgreSQL community and get a deep sense of what the overall community considers "high-quality docs" can itself be a super insightful experience. Different developer communities often need / want a different focus in the docs. That can be the foundation for a fairly authoritative docs quality checklist. Another thing that I'm very interested in, and will need to think through deeply some other day, is this notion that once you publish a doc, you can't touch it. It happens all the time and it's really weird.
actuallyalys 3y ago
As someone who’s been both a software developer and a technical writer, I agree that a lot of these problems seem best suited for a technical writer. The expertise with creating different types of documents is valuable, of course, but there’s another benefit: The organization committing resources in the form of making it someone’s entire responsibility. While I think updating reference documents lends itself to subject matter experts (especially in a project where this approach is already successful), I think structuring them can be separated and given to a technical writer with more technical expertise or a developer with more documentation expertise.
tetha 3y ago
We're seeing similar things at work as the postgres documentation has. We in infra-ops can give you more details about how our database clusters are designed for resilience, security, safety than you want on more levels than most people in the company know exist. We also have reasoning for all of this available. This is really good to have for customer question sets during sales. However, this doesn't tell a developer how to connect his spring boot thingy to it, and how to connect and manage his service well. In fact, 80 - 90% or more of the things we know about our database are not relevant to a simple small-scale application running queries on it. And quite a lot of the issues you can have with running your application on a rock-solid database are entirely not relevant at a DBA level. Like, the database doesn't care if your DDL modification is backwards compatible. And that's something we're currently learning together with a foundation team at work. They are documenting on how to use it well from their side, we're learning about easy mistakes to make and document those, and help with the actionable documentation. And in hard cases we kinda have to talk what's the plan, because it's usually not smart from a DBAs perspective.
- nightpool 3y ago
  How many small/new services do you have, and how many developers / teams do you have? If most of your developers are working on "small-scale applications running queries", aren't you just spending a lot of developer time on repeating the same work over and over again?
  - burnished 3y ago
    Reusable components and code generation covers this pretty well.
    - nightpool 3y ago
      "However, this doesn't tell a developer how to connect his spring boot thingy to it, and how to connect and manage his service well" indicates that it does not
      - 3y ago
_sharp 3y ago
Our team recently adopted the Diataxis framework, I guess. We followed this guide: https://documentation.divio.com/ https://documentation.divio.com/ We've been referring to it as the Divio system though, which appears to be the same thing.
BSEdlMMldESB 3y ago
we need to develop the techniques (and then the tooling) so that the source code is sufficient to reconstruct the documentation. LLMs are fit for this use. I think they could get trained on assembly language. further, I think that at this point, the whole x86 spec is as impossible to analyze 'rationally' as any natural language. funny that it was created by dozens upon dozens of engineers in a rigorous and formal way; and the result is now mega complex. but I digress... my point is to reconsider x86 spec as a 'natural' language which is the common "tongue" between software and PC hardware. but by this point there's no expectation that a modern intel cpu is implementing the instructions in the way they were first created. it may well be emulating the x86 spec to the best of its capacity (another computer program "written" in 'microcode', a x86 virtual machine); so when thinking about x86 assembly spec as a language, the software computer is talking to the hardware computer; and if they agree the computer works. (so the socket and motherboard's buses can be understood as network devices xP ) finally, if I can come up with this (LLMs trained on assembly) so can any security researcher from any advanced academy or corporation.... meaning security researches NOT using LLMs like this ones I imagined are not doing their jobs correctly.

btilly 3y ago

Just curious. Where do you think that an open source project like PostgreSQL gets a budget to hire anyone? Let alone to dictate a new line of authority to the volunteers who are already maintaining it? And don't forget that there are valuable volunteers who are likely to go elsewhere if too many new rules are added that they don't want to live with.

kaycebasques 3y ago
Open Web Docs is a potential model to draw inspiration from regarding funding: https://openwebdocs.org https://openwebdocs.org Presumably, PostgreSQL has leaders who are responsible for steering the ship. If the project is going to succeed long-term, those leaders have to find ways to keep their contributors happy while also creating an organizational structure that leads to good docs. Easier said than done, I know, but it really is as simple as that. Sorry if any of my comments came off naive or obtuse when it comes to open source dynamics. But the reality is that you need good docs, and I'm just trying to give an honest assessment from my experience of the conditions that lead to good docs.
- btilly 3y ago
  Sorry if any of my comments came off naive or obtuse when it comes to open source dynamics. If you want that apology to be meaningful, you should learn something. When you're talking about a highly successful open source project that has been going for more than 3 decades, it is beyond ludicrous for you to say, "If the project is going to succeed long-term..." It already has succeeded long-term. And you would be better off figuring out why it works rather than lecturing about how it must work. When you talk about "a potential model to draw from" for funding, please note that I've been involved with open source for about a quarter of a century. I've seen a LOT of funding models attempted. Mostly they run into one big problem. And that problem is that adding funding creates bruised egos because people say, "Why is he getting paid when I'm not?" The one funding model that DOESN'T have this problem is when a company decides to pay its employees to work on features that it wants in the project. Now there are no bruised egos - the money comes from the company and it is clear why one person gets paid while another does not. There are still challenges with this model - employees are under pressure to get their contributions accepted whether or not the project likes them - but we've learned how to navigate those. But now we're left back where we started. Companies who hire core developers don't generally need comprehensive documentation - they build internal documentation straight for their use case. So comprehensive external documentation is hard to find. Sometimes you'll wind up with things like an excellent introductory tutorial like https://docs.python.org/3/tutorial/ https://docs.python.org/3/tutorial/. Usually, you don't. And generally it is hard to simply pay someone to take care of it for you.

kaycebasques 3y ago

Just re-read the last two paragraphs from Haas. I have a couple further comments / questions. Quote from Haas: > But if on the other hand I propose some change to documentation that has existed for a long time, or some kind of structural change, there's a lot more room for disagreement. Because the change isn't strictly mechanical, the right answer is a lot more subjective. And because it's a change to existing content rather than the addition of new content, many more people will be familiar with it and have opinions on how it ought to be changed, if at all. Consequently, even when some developer does take time away from writing code to try to make some larger change to the documentation, it's often an uphill battle to get anything done, and people typically have to be content with small improvements. Honest question: do PostgreSQL engineering decisions have the same dynamics as what's described here for docs decisions? If not, what is different about engineering decisions versus docs decisions? Is it just that engineering decisions can be literally benchmarked whereas docs decisions do not seem benchmark-able? Are there any other potential explanations for different dynamics between eng and docs? If it does indeed just boil down to "docs are not benchmarkable" then I would suggest otherwise. You can create docs benchmarks. They won't have the rigor of engineering benchmarks but they at least establish some notion of docs quality and facilitate more targeted discussions during docs reviews. E.g. when there's a disagreement between an author and reviewer the author can say, "what docs benchmarks am I not following here?" The power of that kind of interaction is that you often do realize that the docs benchmarks are incomplete and some new dimension needs to be added to them. Or do the PostgreSQL contributor docs already have some guidelines along the lines of a "content quality checklist" and it's still not working? A rigorous effort to survey the PostgreSQL community and get a deep sense of what the overall community considers "high-quality docs" can itself be a super insightful experience. Different developer communities often need / want a different focus in the docs. That can be the foundation for a fairly authoritative docs quality checklist. Another thing that I'm very interested in, and will need to think through deeply some other day, is this notion that once you publish a doc, you can't touch it. It happens all the time and it's really weird.

actuallyalys 3y ago

As someone who’s been both a software developer and a technical writer, I agree that a lot of these problems seem best suited for a technical writer. The expertise with creating different types of documents is valuable, of course, but there’s another benefit: The organization committing resources in the form of making it someone’s entire responsibility. While I think updating reference documents lends itself to subject matter experts (especially in a project where this approach is already successful), I think structuring them can be separated and given to a technical writer with more technical expertise or a developer with more documentation expertise.

tetha 3y ago

We're seeing similar things at work as the postgres documentation has. We in infra-ops can give you more details about how our database clusters are designed for resilience, security, safety than you want on more levels than most people in the company know exist. We also have reasoning for all of this available. This is really good to have for customer question sets during sales. However, this doesn't tell a developer how to connect his spring boot thingy to it, and how to connect and manage his service well. In fact, 80 - 90% or more of the things we know about our database are not relevant to a simple small-scale application running queries on it. And quite a lot of the issues you can have with running your application on a rock-solid database are entirely not relevant at a DBA level. Like, the database doesn't care if your DDL modification is backwards compatible. And that's something we're currently learning together with a foundation team at work. They are documenting on how to use it well from their side, we're learning about easy mistakes to make and document those, and help with the actionable documentation. And in hard cases we kinda have to talk what's the plan, because it's usually not smart from a DBAs perspective.

nightpool 3y ago
How many small/new services do you have, and how many developers / teams do you have? If most of your developers are working on "small-scale applications running queries", aren't you just spending a lot of developer time on repeating the same work over and over again?
- burnished 3y ago
  Reusable components and code generation covers this pretty well.
  - nightpool 3y ago
    "However, this doesn't tell a developer how to connect his spring boot thingy to it, and how to connect and manage his service well" indicates that it does not
    - 3y ago

_sharp 3y ago

Our team recently adopted the Diataxis framework, I guess. We followed this guide: https://documentation.divio.com/ https://documentation.divio.com/ We've been referring to it as the Divio system though, which appears to be the same thing.

BSEdlMMldESB 3y ago

we need to develop the techniques (and then the tooling) so that the source code is sufficient to reconstruct the documentation. LLMs are fit for this use. I think they could get trained on assembly language. further, I think that at this point, the whole x86 spec is as impossible to analyze 'rationally' as any natural language. funny that it was created by dozens upon dozens of engineers in a rigorous and formal way; and the result is now mega complex. but I digress... my point is to reconsider x86 spec as a 'natural' language which is the common "tongue" between software and PC hardware. but by this point there's no expectation that a modern intel cpu is implementing the instructions in the way they were first created. it may well be emulating the x86 spec to the best of its capacity (another computer program "written" in 'microcode', a x86 virtual machine); so when thinking about x86 assembly spec as a language, the software computer is talking to the hardware computer; and if they agree the computer works. (so the socket and motherboard's buses can be understood as network devices xP ) finally, if I can come up with this (LLMs trained on assembly) so can any security researcher from any advanced academy or corporation.... meaning security researches NOT using LLMs like this ones I imagined are not doing their jobs correctly.