<instructions>Your goal is to analyze the following comment and estimate how highly it will be upvoted by the Hacker News community.</instructions><comment><author>dllthomas</author><text>I&amp;#x27;ve taken to supporting cross-references across the repo, connecting references of the form ^^{foo} to anchors of the form @@{foo}, wherever they appear (code, comment, docs).&lt;p&gt;Then I have CI check referential integrity and also surface connections in code review (adding annotations to all references when the corresponding anchor shows up in the diff in changed lines or context, and vice-versa).&lt;p&gt;In the idealized straight-forward elaboration, then, all docs would live in the repo, but I haven&amp;#x27;t worked with a team that was on board with that.&lt;p&gt;I&amp;#x27;d also like to see a better tie between docs and tests.</text><parent_chain><item><author>kaycebasques</author><text>Hi I&amp;#x27;ve been a technical writer for ~9 years: 3 at a startup and 6 at Google. I agree that documentation maintenance is probably the real hard problem. I think the winner of this space will be the one who solves the &amp;quot;connect code to documentation&amp;quot; aspect most effectively. Looking at your demo, I don&amp;#x27;t think the code&amp;#x2F;doc connection should be invisible metadata. In other words my hunch is that the code&amp;#x2F;doc connection needs to be obvious in code&amp;#x2F;doc themselves although I&amp;#x27;m not sure why I feel this way at the moment. Also the root causes of stale documentation are usually a combination of 1) documentation not being incentivized by org leadership 2) the gradual but persistent proliferation of docs. I don&amp;#x27;t mean to say that these are people problems that are not solvable by technology. I do think they are solvable by technology but you&amp;#x27;ll need to get very creative and innovative to solve them. E.g. to address #1 maybe some kind of reporting system that makes leadership aware of which engineers are doing docs work that is truly creating value for the org. Happy to chat 1:1 and thank you for bringing innovations to my industry!</text></item></parent_chain></comment><story><title>Launch HN: Mintlify (YC W22) – Maintainable documentation for software teams</title><text>Hi HN, we’re Hahnbee and Han from Mintlify (&lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;www.mintlify.com&amp;#x2F;&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;www.mintlify.com&amp;#x2F;&lt;/a&gt;). Mintlify lets software teams easily track and manage documentation. We’re open source and our Github is at &lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;github.com&amp;#x2F;mintlify&amp;#x2F;mintlify&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;github.com&amp;#x2F;mintlify&amp;#x2F;mintlify&lt;/a&gt;.&lt;p&gt;We worked at software companies in all stages ranging from startups to big tech, and they all had bad documentation, if it even existed at all. We decided to work on this problem and created a VS Code extension called Doc Writer which generated in-line documentation for codebases using Codex from OpenAI. Doc Writer helped people document their code more frequently and still continues to, but there were limitations. We were highly reliant on OpenAI, people didn’t want their proprietary code to be sent into the cloud, and the AI was satisfactory 80% of the time. But after digging deeper into the documentation problem space, we realized that Doc Writer only solved a small part of it.&lt;p&gt;We quickly learned that (1) the debate about writing documentation vs. having self-documenting code was highly controversial, and (2) entire teams hated writing documentation—not only developers.&lt;p&gt;We proceeded to interview dozens of startups and learned that the hardest part about documentation is maintaining it. Everybody was developing so quickly that it was difficult for documentation to stay up-to-date. Common problems we heard were that documentation was inconveniently decentralized over multiple platforms, people weren’t aware when important documents changed, and when code changes the related documentation wouldn’t be updated.&lt;p&gt;The goal of Mintlify is to increase visibility over documentation across your entire team so that you can easily maintain it. Mintlify allows you to centralize your documentation into one searchable place; set up integrations to receive alerts when documents change; implement a CI Check for documentation - connect documentation to code and receive alerts to update your documentation when the code changes.&lt;p&gt;Other solutions to the problem of documentation maintenance tend to create an editor (e.g. Notion, ReadMe, Archbee, Gitbook). We decided instead to work with teams’ existing documentation stack, because of our belief that maintenance of documentation is the real hard problem in this space. Our software is designed to help documentation owners ensure that content stays in good condition.&lt;p&gt;Here is our 2 min demo: &lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;www.loom.com&amp;#x2F;share&amp;#x2F;892d08e178144cd89b109f9396e4db98&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;www.loom.com&amp;#x2F;share&amp;#x2F;892d08e178144cd89b109f9396e4db98&lt;/a&gt;, and you can also try it for yourself: &lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;www.mintlify.com&amp;#x2F;create&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;www.mintlify.com&amp;#x2F;create&lt;/a&gt;&lt;p&gt;Ultimately, we want to create a suite of automations that makes maintaining high quality documentation easy. We plan on adding documentation owners and integrations with task management platforms so that tickets can be instantly generated prompting people to update documentation. We believe there is a market for this because of our experience with our earlier Doc Writer product, and because companies like Glean, Gitbook, and Whatfix are all tackling this problem in their own way.&lt;p&gt;We thank the open source community, our community, and our users for having helped us shape the product to what it is now. We look forward to your feedback, questions, ideas, and suggestions!</text></story>
<instructions>Your goal is to analyze the following comment and estimate how highly it will be upvoted by the Hacker News community.</instructions><comment><author>hanyiwang</author><text>Thank you so much for the incredible feedback! We think you are absolutely SPOT ON. We would really love to chat more with you 1:1. Please reach out to us at han@mintlify.com</text><parent_chain><item><author>kaycebasques</author><text>Hi I&amp;#x27;ve been a technical writer for ~9 years: 3 at a startup and 6 at Google. I agree that documentation maintenance is probably the real hard problem. I think the winner of this space will be the one who solves the &amp;quot;connect code to documentation&amp;quot; aspect most effectively. Looking at your demo, I don&amp;#x27;t think the code&amp;#x2F;doc connection should be invisible metadata. In other words my hunch is that the code&amp;#x2F;doc connection needs to be obvious in code&amp;#x2F;doc themselves although I&amp;#x27;m not sure why I feel this way at the moment. Also the root causes of stale documentation are usually a combination of 1) documentation not being incentivized by org leadership 2) the gradual but persistent proliferation of docs. I don&amp;#x27;t mean to say that these are people problems that are not solvable by technology. I do think they are solvable by technology but you&amp;#x27;ll need to get very creative and innovative to solve them. E.g. to address #1 maybe some kind of reporting system that makes leadership aware of which engineers are doing docs work that is truly creating value for the org. Happy to chat 1:1 and thank you for bringing innovations to my industry!</text></item></parent_chain></comment><story><title>Launch HN: Mintlify (YC W22) – Maintainable documentation for software teams</title><text>Hi HN, we’re Hahnbee and Han from Mintlify (&lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;www.mintlify.com&amp;#x2F;&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;www.mintlify.com&amp;#x2F;&lt;/a&gt;). Mintlify lets software teams easily track and manage documentation. We’re open source and our Github is at &lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;github.com&amp;#x2F;mintlify&amp;#x2F;mintlify&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;github.com&amp;#x2F;mintlify&amp;#x2F;mintlify&lt;/a&gt;.&lt;p&gt;We worked at software companies in all stages ranging from startups to big tech, and they all had bad documentation, if it even existed at all. We decided to work on this problem and created a VS Code extension called Doc Writer which generated in-line documentation for codebases using Codex from OpenAI. Doc Writer helped people document their code more frequently and still continues to, but there were limitations. We were highly reliant on OpenAI, people didn’t want their proprietary code to be sent into the cloud, and the AI was satisfactory 80% of the time. But after digging deeper into the documentation problem space, we realized that Doc Writer only solved a small part of it.&lt;p&gt;We quickly learned that (1) the debate about writing documentation vs. having self-documenting code was highly controversial, and (2) entire teams hated writing documentation—not only developers.&lt;p&gt;We proceeded to interview dozens of startups and learned that the hardest part about documentation is maintaining it. Everybody was developing so quickly that it was difficult for documentation to stay up-to-date. Common problems we heard were that documentation was inconveniently decentralized over multiple platforms, people weren’t aware when important documents changed, and when code changes the related documentation wouldn’t be updated.&lt;p&gt;The goal of Mintlify is to increase visibility over documentation across your entire team so that you can easily maintain it. Mintlify allows you to centralize your documentation into one searchable place; set up integrations to receive alerts when documents change; implement a CI Check for documentation - connect documentation to code and receive alerts to update your documentation when the code changes.&lt;p&gt;Other solutions to the problem of documentation maintenance tend to create an editor (e.g. Notion, ReadMe, Archbee, Gitbook). We decided instead to work with teams’ existing documentation stack, because of our belief that maintenance of documentation is the real hard problem in this space. Our software is designed to help documentation owners ensure that content stays in good condition.&lt;p&gt;Here is our 2 min demo: &lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;www.loom.com&amp;#x2F;share&amp;#x2F;892d08e178144cd89b109f9396e4db98&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;www.loom.com&amp;#x2F;share&amp;#x2F;892d08e178144cd89b109f9396e4db98&lt;/a&gt;, and you can also try it for yourself: &lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;www.mintlify.com&amp;#x2F;create&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;www.mintlify.com&amp;#x2F;create&lt;/a&gt;&lt;p&gt;Ultimately, we want to create a suite of automations that makes maintaining high quality documentation easy. We plan on adding documentation owners and integrations with task management platforms so that tickets can be instantly generated prompting people to update documentation. We believe there is a market for this because of our experience with our earlier Doc Writer product, and because companies like Glean, Gitbook, and Whatfix are all tackling this problem in their own way.&lt;p&gt;We thank the open source community, our community, and our users for having helped us shape the product to what it is now. We look forward to your feedback, questions, ideas, and suggestions!</text></story>