Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

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

news.ycombinator.com

Post reply on HN
Print view View original

41–50 of 59 posts

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

#41

Post by pixel_tracing »

kaycebasques wrote: post #11

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 n…

I agree with your sentiments have you looked at how Apple has integrated Doc-C with Xcode?

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

#43

Post by zild3d »

lifeisstillgood wrote: post #37

Just a note based on the demo video above 1. it starts with the worst possible feature (if I chnage the docs then a slack notification is sent to everyone). 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. I am missing the killer app here - surely going from the docs (ie this docentions this function) would automate the linkage but…

> 1. it starts with the worst possible feature (if I chnage the docs then a slack notification is sent to everyone).

They show the update going to a #docs channel, that doesn't mean it notifies everyone. It notifies whoever wants to be notified of updates posted to the #docs channel. Currently using something similar for notion, channel membership is opt in, and most have notifications silenced

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

#44

Post by lifeisstillgood »

zild3d wrote: post #43
lifeisstillgood wrote: post #37

Just a note based on the demo video above 1. it starts with the worst possible feature (if I chnage the docs then a slack notification is sent to everyone). 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. I am missing the killer app here - surely going from the docs (ie this docentions this function) would automate the linkage but…

> 1. it starts with the worst possible feature (if I chnage the docs then a slack notification is sent to everyone). They show the update going to a #docs channel, that doesn't mean it notifies everyone. It notifies whoever wants to be notified of updates posted to the #docs channel. Currently using something similar for notion, channel membership is opt in, and most have notifications silenced

Fair enough (the words "notifies everyone" probably should be chanaged.)

But that's not really the point - it's that I don't get what they are doing that beats me coding something in an afternoon. (Inam trying really hard not to do the famous Dropbox comment)

But afaik the main feature here is you can add a piece of metadata in a comment that says "if this module is chnaged in a release branch, then some other documentation file must also be chnaged in the same branch.

Now, yeah that's kind of good as a policy. But if I am using docutils and my index.rst has a reference to "foo.bar.addmoney" then I can see how to set up a pre-commit hook and some worker that will do the same thing.

Now this is a pretty good feature to add to say Jenkins or GitHub Actions.

I could see that being a desirable feature for some set of teams.

I just don't like the "add extra meta data" thing, and I don't see what the win is outside of the CI tools

(not too sure how they are hooking into the CI ecosystems)

But hell good luck to you guys, you are in the arena. well done - good luck and I hope it works out.

Just please stop and work on that elevator pitch so that I do get it. I mean Inam interested enough in this area that i watched a video, read thirty comments and replied a couple of times.

I should be the perfect target customer.

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

#45

Post by hahnbee »

movedx wrote: post #34
hanyiwang wrote: post #25

Earlier quoted context omitted.

We totally agree! We think it would be best when documentation is centralized, version controlled, and coupled with the code. Unfortunately, we realized that's just not the case for the vast majority of companies. One way to think about our product is just bringing the features of documentation on GitHub into existing documentation that lives outside of it.

A potentially valueable goal. I wish you luck. > Unfortunately, we realized that's just not the case for the vast majority of companies. Nor is DevOps, but that's changing. And as more things shift-left and get actioned in a CI/CD pipeline, companies are going to want more automation, checks, analysis, etc., of all their digital assets. That includes documentation - spell checks, auto-generated and static, checking f…

> how do we keep documentation close to the context to which it relates, AND allow it to be manipulated, tested, and more, all through automated business logic? Solve that.

Well spoken.

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

#46

Post by hahnbee »

ethanwillis wrote: post #36

I think this is really just level 0 of what documentation is from everything I'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/level 0 I would caution you to keep in mind incentives to try and avoid perverse incentives Right now there are close to 0 incentives to either create…

Your point about incentivizing is very interesting. We mainly interviewed teams that were in our batch AKA early stage startups/small teams that didn't have much of a divide between management and developers - definitely a mistake on our part and we should definitely go back to interviewing larger teams. We knew that documentation is hard to maintain as changes are made and that a feature can be shipped without documentation having to be written/updated. We also agree that whatever our solution is - we need to be opinionated in terms of the "cultural, management, implementation, and usage standards and habits". I totally see where you're coming from about this being level 0 - at the very least we create visibility that something may or may not be updated. I guess the assumption we made was that a CI check would be enough (because the mentality is that you can't merge until you resolve everything) but there's definitely more incentives we can create.

Analytics about documentation is something we've talked about, but it's definitely something we should talk about more seriously.

> What is "bad" documentation and what is "good" documentation?

There are definitely varying levels of granularity I can go into answering this question. As a baseline I can definitely say that bad documentation is documentation that is out-of-date - a series of instructions that are not the correct steps to get to the end goal that it claims will get for you. And good documentation is one in which it does allow you to get to your end goal. However, there are definitely layers to it - because I know for myself I'm very opinionated on how verbose, clear, or straight-to-the-point documentation is. Outside of just the content, there's also a lot that surrounds the structure of documentation.

It's so clear that a problem exists here. We just have to figure out what the best solution looks like.

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

#47

Post by hahnbee »

Grustaf wrote: post #42

Isn'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.

Yeah. We started this whole endeavor because we, as developers, also hated writing documentation. We thought that if we made it easier - whether it's by automating it through AI or by bringing the documentation closer to the code - it would reduce the friction. We definitely think more can be done here to incentivize developers to update documentation.

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

#48

Post by hahnbee »

zild3d wrote: post #43
lifeisstillgood wrote: post #37

Just a note based on the demo video above 1. it starts with the worst possible feature (if I chnage the docs then a slack notification is sent to everyone). 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. I am missing the killer app here - surely going from the docs (ie this docentions this function) would automate the linkage but…

> 1. it starts with the worst possible feature (if I chnage the docs then a slack notification is sent to everyone). They show the update going to a #docs channel, that doesn't mean it notifies everyone. It notifies whoever wants to be notified of updates posted to the #docs channel. Currently using something similar for notion, channel membership is opt in, and most have notifications silenced

Thanks for the feedback! We were planning on adding an ownership layer to it so that you can ping certain people who are the specific people who need to be notified.

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

#49

Post by hanyiwang »

quickthrower2 wrote: post #35
kaycebasques wrote: post #11

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 n…

I agree you need incentives for people to write documentation. Part of documentation is keeping it up to date (as shown in the demo video, keeping code in sync) but another important part is providing a way for newcomers to learn. Reference documentation is different to teaching documentation. Maybe a good platform can encourage this.

Excellent suggestion. We're gonna work this into the product for sure

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

#50

Post by hahnbee »

lifeisstillgood wrote: post #44
zild3d wrote: post #43

Earlier quoted context omitted.

> 1. it starts with the worst possible feature (if I chnage the docs then a slack notification is sent to everyone). They show the update going to a #docs channel, that doesn't mean it notifies everyone. It notifies whoever wants to be notified of updates posted to the #docs channel. Currently using something similar for notion, channel membership is opt in, and most have notifications silenced

Fair enough (the words "notifies everyone" probably should be chanaged.) But that's not really the point - it's that I don't get what they are doing that beats me coding something in an afternoon. (Inam trying really hard not to do the famous Dropbox comment) But afaik the main feature here is you can add a piece of metadata in a comment that says "if this module is chnaged in a release branch, then some other docume…

Thank you, we really appreciate your feedback. We're both technical founders and we're very aware that we need to work on making the language clearer. Your feedback makes it crystal clear that we really need to work on this. Appreciate it.
Post reply on HN