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

21–30 of 59 posts

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

#21

Post by djbusby »

dllthomas wrote: post #15
hahnbee wrote: post #14

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

Non-engineers can edit Asciidoc or Markdown in the GitLab IDE.

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

#22

Post by dllthomas »

hahnbee wrote: post #16
dllthomas wrote: post #15

Earlier quoted context omitted.

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

> apologies for all the questions

No worries at all, it's half of what we're here for :)

> did you implement this for your company?

On a couple repos, yeah.

> many of the comments prefer to have documentation in the repo

I think there's a lot of us, but I also think we're more likely to want to talk about it, so it seems like there's more of us than there are.

I should say that I think most everyone's on board with a small amount of developer facing docs in the repo, especially a README and build instructions; whereas if I had my druthers, it'd even include pamphlets the sales team takes to conferences.

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

#23

Post by movedx »

I find these solutions actually make documentation harder. They're binary and proprietary in nature, locked behind a paywall if I can no longer afford the service (and what's the exportable data going to look like? XML?), And the UI is often limited and leaves a lot to be desired.

My code is not binary, however, it'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 "mkdocs serve" for example).

You're already committing code to a central repository and working in a decentralised manner. If you put your documentation in "./docs/" (I recommend MkDocs + the Material Theme) and commit it, then everyone has access to it immediately. It's free, close to the code and in context, everyone who needs access to it has it, and it's simple to use. It's also local, extremely fast and, if desired, can be easily embedded into a CI pipeline, compiled to anything you like (Markdown => *) and pushed to wherever you like.

I also don't understand the obsession with making documentation available online, 24/7, when we live in a cyber security nightmare right now (https://www.hertzbleed.com/; https://securityboulevard.com/2022/06/apple-m1-flaw-cant-be-...; https://www.darkreading.com/threat-intelligence/emotet-banki...; https://www.darkreading.com/edge-articles/turbulent-cyber-in....)

Just keep it within context, plain text, and easily convertible to other formats. Try not to over think things.

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

#24

Post by dllthomas »

kaycebasques wrote: post #17
dllthomas wrote: post #13

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

Thanks! At the moment it feels much too small to productize; virtually all of the complexity is the CI integration, and even that is small.

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

#25

Post by hanyiwang »

movedx wrote: post #23

I find these solutions actually make documentation harder. They're binary and proprietary in nature, locked behind a paywall if I can no longer afford the service (and what's the exportable data going to look like? XML?), And the UI is often limited and leaves a lot to be desired. My code is not binary, however, it's plain text. So I write my documentation in plain text too, such as Markdown. That can, should I so ch…

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.

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

#26

Post by dllthomas »

djbusby wrote: post #21
dllthomas wrote: post #15

Earlier quoted context omitted.

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

Non-engineers can edit Asciidoc or Markdown in the GitLab IDE.

True. Seems potentially very useful, but only relevant if you're using GitLab and want a relevant format (or something you can reasonably produce from a relevant format, although tooling questions then get potentially more complicated).

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

#27

Post by hahnbee »

dllthomas wrote: post #22
hahnbee wrote: post #16

Earlier quoted context omitted.

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.

> apologies for all the questions No worries at all, it's half of what we're here for :) > did you implement this for your company? On a couple repos, yeah. > many of the comments prefer to have documentation in the repo I think there's a lot of us, but I also think we're more likely to want to talk about it, so it seems like there's more of us than there are. I should say that I think most everyone's on board with a…

Yeah, that honestly makes a lot of sense.

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

#29

Post by hanyiwang »

nullcipher wrote: post #28

The opening line says "Open source" , but they aren't. Source available is the correct term.

Totally agreed. While the frontend and core functions are open source, the backend under the `server` folder is source available. We made the mistake of referring to the entire repo as open source, which we will refrain from in the future.

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

#30

Post by infogulch »

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…

What do you think about documentation organization methodologies? And this one in particular: https://documentation.divio.com/
Post reply on HN