TE
科技回声
首页24小时热榜最新最佳问答展示工作
GitHubTwitter
首页

科技回声

基于 Next.js 构建的科技新闻平台,提供全球科技新闻和讨论内容。

GitHubTwitter

首页

首页最新最佳问答展示工作

资源链接

HackerNews API原版 HackerNewsNext.js

© 2025 科技回声. 版权所有。

Launch HN: Mintlify (YC W22) – Maintainable documentation for software teams

149 点作者 hahnbee将近 3 年前
Hi HN, we’re Hahnbee and Han from Mintlify (<a href="https:&#x2F;&#x2F;www.mintlify.com&#x2F;" rel="nofollow">https:&#x2F;&#x2F;www.mintlify.com&#x2F;</a>). Mintlify lets software teams easily track and manage documentation. We’re open source and our Github is at <a href="https:&#x2F;&#x2F;github.com&#x2F;mintlify&#x2F;mintlify" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;mintlify&#x2F;mintlify</a>.<p>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.<p>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.<p>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.<p>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.<p>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.<p>Here is our 2 min demo: <a href="https:&#x2F;&#x2F;www.loom.com&#x2F;share&#x2F;892d08e178144cd89b109f9396e4db98" rel="nofollow">https:&#x2F;&#x2F;www.loom.com&#x2F;share&#x2F;892d08e178144cd89b109f9396e4db98</a>, and you can also try it for yourself: <a href="https:&#x2F;&#x2F;www.mintlify.com&#x2F;create" rel="nofollow">https:&#x2F;&#x2F;www.mintlify.com&#x2F;create</a><p>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.<p>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!

10 条评论

kaycebasques将近 3 年前
Hi I&#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 &quot;connect code to documentation&quot; aspect most effectively. Looking at your demo, I don&#x27;t think the code&#x2F;doc connection should be invisible metadata. In other words my hunch is that the code&#x2F;doc connection needs to be obvious in code&#x2F;doc themselves although I&#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&#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&#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!
评论 #31743621 未加载
评论 #31743512 未加载
评论 #31749457 未加载
评论 #31749880 未加载
评论 #31748026 未加载
评论 #31750660 未加载
learndeeply将近 3 年前
If anyone is wondering, Mintlify is not open source: <a href="https:&#x2F;&#x2F;github.com&#x2F;mintlify&#x2F;mintlify&#x2F;blob&#x2F;main&#x2F;server&#x2F;LICENSE" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;mintlify&#x2F;mintlify&#x2F;blob&#x2F;main&#x2F;server&#x2F;LICENS...</a>
评论 #31746494 未加载
lifeisstillgood将近 3 年前
Just a note based on the demo video above<p>1. it starts with the worst possible feature (if I chnage the docs then a slack notification is sent to everyone).<p>2. the code link feature is ... ok. It prevents a merge on certain code modules if the docs have not also been updated. Useful I guess.<p>I am missing the killer app here - surely going from the docs (ie this docentions this function) would automate the linkage but even so it seems a nice to have feature not the &quot;aha&quot; moment<p>Anyhow sorry for the usual negative HN tone - good luck
评论 #31751893 未加载
irq-1将近 3 年前
Random thought: maybe you could connect a UI component (or State, or Service call) to a function chain and types used. Then reviewing a document could include links to code changes. It would be difficult to automatically determine which code changes matter. Programmers might be able to @ttribute functions, or include checking tags&#x2F;links. Anyway, documents that are not one-to-one with a code file seem like the hardest to keep up to update.
评论 #31743297 未加载
nullcipher将近 3 年前
The opening line says &quot;Open source&quot; , but they aren&#x27;t. Source available is the correct term.
评论 #31747900 未加载
cincinnatus将近 3 年前
We have a highly regulated environment and supply chain and have to go through a whole lot of GRC on a regular basis, and additionally one-off audits from some customers before they&#x27;ll feel ok using our solution. So I will share here what I said to my folks:<p>&quot;I looked further at the documentation solution I mentioned looked interesting. It is very nifty but it is pure SaaS, and I don&#x27;t care how secure they are, having our source flow through another SaaS is not something I&#x27;m going to take on for any amount of pixy dust.&quot;
评论 #31759028 未加载
ushakov将近 3 年前
sounds interesting<p>i’m working on Typosaur, which is a spell-checker that can check websites (or any structured document really) for spelling mistakes, grammar and style issues and suggest corrections<p>link: <a href="https:&#x2F;&#x2F;typosaur.com&#x2F;" rel="nofollow">https:&#x2F;&#x2F;typosaur.com&#x2F;</a><p>maybe you’d be interested in integrating Typosaur-powered spelling suggestions into your offering?<p>if so my e-mail is linked in profile
评论 #31742930 未加载
Grustaf将近 3 年前
Isn&#x27;t the underlying problem that developers hate writing documentation for some reason? They will spend months writing some crazy audio framework in C++ but refuse to spend even a day writing a tutorial on how to install it.
评论 #31753592 未加载
movedx将近 3 年前
I find these solutions actually make documentation harder. They&#x27;re binary and proprietary in nature, locked behind a paywall if I can no longer afford the service (and what&#x27;s the exportable data going to look like? XML?), And the UI is often limited and leaves a lot to be desired.<p>My code is not binary, however, it&#x27;s plain text. So I write my documentation in plain text too, such as Markdown. That can, should I so choose, be rendered to anything I like. It can be included alongside the code, which the developer will need a copy of anyway, and be easily reviewed (with &quot;mkdocs serve&quot; for example).<p>You&#x27;re already committing code to a central repository and working in a decentralised manner. If you put your documentation in &quot;.&#x2F;docs&#x2F;&quot; (I recommend MkDocs + the Material Theme) and commit it, then everyone has access to it immediately. It&#x27;s free, close to the code and in context, everyone who needs access to it has it, and it&#x27;s simple to use. It&#x27;s also local, extremely fast and, if desired, can be easily embedded into a CI pipeline, compiled to anything you like (Markdown =&gt; *) and pushed to wherever you like.<p>I also don&#x27;t understand the obsession with making documentation available online, 24&#x2F;7, when we live in a cyber security nightmare right now (<a href="https:&#x2F;&#x2F;www.hertzbleed.com&#x2F;;" rel="nofollow">https:&#x2F;&#x2F;www.hertzbleed.com&#x2F;;</a> <a href="https:&#x2F;&#x2F;securityboulevard.com&#x2F;2022&#x2F;06&#x2F;apple-m1-flaw-cant-be-fixed-pacman-panic&#x2F;;" rel="nofollow">https:&#x2F;&#x2F;securityboulevard.com&#x2F;2022&#x2F;06&#x2F;apple-m1-flaw-cant-be-...</a> <a href="https:&#x2F;&#x2F;www.darkreading.com&#x2F;threat-intelligence&#x2F;emotet-banking-trojan-resurfaces-email-security;" rel="nofollow">https:&#x2F;&#x2F;www.darkreading.com&#x2F;threat-intelligence&#x2F;emotet-banki...</a> <a href="https:&#x2F;&#x2F;www.darkreading.com&#x2F;edge-articles&#x2F;turbulent-cyber-insurance-market-sees-rising-prices-and-sinking-coverage" rel="nofollow">https:&#x2F;&#x2F;www.darkreading.com&#x2F;edge-articles&#x2F;turbulent-cyber-in...</a>.)<p>Just keep it within context, plain text, and easily convertible to other formats. Try not to over think things.
评论 #31747454 未加载
ethanwillis将近 3 年前
I think this is really just level 0 of what documentation is from everything I&#x27;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&#x2F;level 0 I would caution you to keep in mind <i>incentives</i> to try and avoid <i>perverse incentives</i><p>Right now there are close to 0 incentives to either create or maintain documentation unless they&#x27;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 <i>lots</i> of external developers that can&#x27;t be interfaced with in a higher touch way).<p>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 <i>good</i> 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.<p>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 <i>dread.</i> I personally love batched tasks that are <i>relevant</i> and <i>important</i>. 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.<p>1 and 2 above can be generalized a bit. With the additional tooling you build on top of your &quot;backbone&quot; you are setting cultural, management, implementation, and usage standards and habits!<p>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&#x27;s not always just internal teams. What tasks are 3rd parties trying to solve with the documentation? Very granular documentation requires a &quot;wide walk&quot; 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?<p>Edit: And to keep this from becoming much longer than it already is :) I have one final important question.<p>What is &quot;bad&quot; documentation and what is &quot;good&quot; documentation?
评论 #31753511 未加载