Hacker News Reader

Comment by dllthomas | Hacker News Reader

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.

View on HN

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

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)

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.

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.

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.

Yeah, that honestly makes a lot of sense.

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

Reply on news.ycombinator.com