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!
Launch HN: Mintlify (YC W22) – Maintainable documentation for software teams
11–20 of 59 posts
Re: Launch HN: Mintlify (YC W22) – Maintainable documentation for software teams
#12Hi 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 n…
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
Re: Launch HN: Mintlify (YC W22) – Maintainable documentation for software teams
#13Hi 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 n…
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.
Re: Launch HN: Mintlify (YC W22) – Maintainable documentation for software teams
#14Hi 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 n…
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 stra…
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?
Re: Launch HN: Mintlify (YC W22) – Maintainable documentation for software teams
#15Earlier quoted context omitted.
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 stra…
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?
> 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.
Re: Launch HN: Mintlify (YC W22) – Maintainable documentation for software teams
#16Earlier quoted context omitted.
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?
> 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 g…
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/comments/v6yuu5/whats_your_d... and many of the comments prefer to have documentation in the repo.
Re: Launch HN: Mintlify (YC W22) – Maintainable documentation for software teams
#17Hi 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 n…
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 stra…
> 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...
Re: Launch HN: Mintlify (YC W22) – Maintainable documentation for software teams
#18Earlier quoted context omitted.
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 stra…
> 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.o…
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)
Re: Launch HN: Mintlify (YC W22) – Maintainable documentation for software teams
#19If anyone is wondering, Mintlify is not open source: https://github.com/mintlify/mintlify/blob/main/server/LICENS...
Re: Launch HN: Mintlify (YC W22) – Maintainable documentation for software teams
#20If anyone is wondering, Mintlify is not open source: https://github.com/mintlify/mintlify/blob/main/server/LICENS...
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