[HN Gopher] Launch HN: Mintlify (YC W22) - Maintainable document...
___________________________________________________________________
Launch HN: Mintlify (YC W22) - Maintainable documentation for
software teams
Hi HN, we're Hahnbee and Han from Mintlify
(https://www.mintlify.com/). Mintlify lets software teams easily
track and manage documentation. We're open source and our Github is
at https://github.com/mintlify/mintlify. 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. 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. 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. 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. 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. Here is our 2
min demo:
https://www.loom.com/share/892d08e178144cd89b109f9396e4db98, and
you can also try it for yourself: https://www.mintlify.com/create
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. 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!
Author : hahnbee
Score : 86 points
Date : 2022-06-14 15:16 UTC (7 hours ago)
| [deleted]
| averyyip wrote:
| ushakov wrote:
| sounds interesting
|
| 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
|
| link: https://typosaur.com/
|
| maybe you'd be interested in integrating Typosaur-powered
| spelling suggestions into your offering?
|
| if so my e-mail is linked in profile
| hanyiwang wrote:
| We took a look around and am actually really interested!
| Sending you an email to discuss more.
|
| Also, how did you manage to embed any website as an iframe
| without CORS or CSP issues?
| ushakov wrote:
| cool!
|
| the websites are pre-rendered using headless Chrome
|
| the side-effect of this approach is that all the files (like
| images) are embedded into the HTML and the website also loses
| interactivity
|
| works great for static documentation sites however!
| hanyiwang wrote:
| It does indeed. Would love to jam more about this with you
| zkirby wrote:
| irq-1 wrote:
| 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/links. Anyway, documents that are not one-
| to-one with a code file seem like the hardest to keep up to
| update.
| hahnbee wrote:
| Currently we use a repo's git information to create the link
| between code and documentation. We also support many-to-many
| connections so you could granularly choose lines of code to
| connect to documentation. But you make a good point! We could
| definitely do some work with AST parsers to select and connect
| specific functions/components to documentation.
| learndeeply wrote:
| If anyone is wondering, Mintlify is not open source:
| https://github.com/mintlify/mintlify/blob/main/server/LICENS...
| hanyiwang wrote:
| That is correct. The backend covers enterprise features that
| are only source-available, whereas the rest of the application
| is open source. We understand that this can be quite
| misleading, and will refrain from saying that we are open
| source in the future
| kaycebasques wrote:
| Hi I'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 "connect code to documentation" aspect
| most effectively. Looking at your demo, I don't think the
| code/doc connection should be invisible metadata. In other words
| my hunch is that the code/doc connection needs to be obvious in
| code/doc themselves although I'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'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'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!
| hanyiwang wrote:
| 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
| dllthomas wrote:
| I'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).
|
| 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).
|
| In the idealized straight-forward elaboration, then, all docs
| would live in the repo, but I haven't worked with a team that
| was on board with that.
|
| I'd also like to see a better tie between docs and tests.
| kaycebasques wrote:
| > In the idealized straight-forward elaboration, then, all
| docs would live in the repo, but I haven't worked with a team
| that was on board with that
|
| In case you're thinking about productizing your work I just
| want to give you a little encouragement that there are a lot
| of companies OK with having docs live alongside code. See
| Google's g3doc [1] for example. See also the _docs as code_
| movement.
|
| [1] https://www.usenix.org/conference/srecon16europe/program/
| pre...
| hanyiwang wrote:
| Thank you for sharing the article! We definitely don't see
| companies having all docs in their repos, but strongly
| believe that there should be stronger ties between docs and
| code (and more transparency in docs in general)
|
| It's a really hard problem to solve, but we believe that
| there will be a product that will crack it (even if it's
| not what we have right now)
| hahnbee wrote:
| That's very interesting. How did you implement this? : "I'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)." Do
| you have a link? Would love to check it out myself. I'm also
| curious - why do you think most people are against docs
| living inside the repo?
| dllthomas wrote:
| > How did you implement this?
|
| It wasn't public code, so no links handy, but the
| implementation was pretty much what you'd expect.
|
| For checking referential integrity, make a list of all
| references and a list of all referents and diff the two.
| Trivial with git grep and a little bash, but pick your
| poison.
|
| For surfacing connections, it was a matter of finding them
| in changes (which was approximately piping git diff to
| grep) , finding the corresponding locations in the whole
| repo, and then adding those locations to the PR, for which
| I used the github Checks API (you can add annotations in
| the output of a Check Run, see
| https://docs.github.com/en/rest/checks/runs#create-a-
| check-r...).
|
| > why do you think most people are against docs living
| inside the repo?
|
| For internal docs, I think it's an impression that Notion
| or Google Docs or Confluence or whatever is "easier",
| although it's usually been easier to get some measure of
| buy-in for at least some set of internal docs.
|
| For external docs, it's "of course we can't teach git to
| anyone but engineers!" Which hasn't tracked my limited
| experience in trying to do so, but it can be hard to get
| them to try to learn in the first place.
| hahnbee wrote:
| Gotcha, apologies for all the questions - did you
| implement this for your company?
|
| That's interesting that the reception you got was
| primarily against documentation inside a repo. Maybe
| Gitbook could've been a good compromise? I recently made
| this post on reddit https://www.reddit.com/r/devops/comme
| nts/v6yuu5/whats_your_d... and many of the comments
| prefer to have documentation in the repo.
___________________________________________________________________
(page generated 2022-06-14 23:00 UTC)