I'm watching Readme.com's new editor preview. Looks great, more like Notion. A user mentioned that they keep all of their docs in version control, then use Readme's API to sync. We already do this for reference docs. Thoughts on doing this for everything?

That's how we used to do things. At one point it was deemed wise to keep docs next to source - more likely to keep in sync in the PR that changes / removes / adds code. Then new wisdom said commits are hard and discourage doc fixes. So we've thrashed.

in-repo docs empower non-maintainers to edit the docs, FWIW

Acknowledged. As someone who works on the docs a ton, my main issue with current setup is: • not having enough review of my changes • too hard to see the history of a page, e.g. git blame • too hard to audit when things need to be changed, such as when we rename a field. It would be very helpful to have ripgrep What I think maybe different from v1 docs: • we will still have distinct versions for each release • if you want to preview the change, you can copy and paste the code into readme. I vaguely remember it being too hard to know before how my change would render

(and allows docs to be changed atomically with code)

in-repo docs empower non-maintainers to edit the docs

They can do this via "suggest edits" button, which people often do use. Thoughts on which is more empowering?

in-repo docs empower non-maintainers to edit the docs, FWIW

This was nacked by the 2nd wisdom phase. Some consensus said commits were hard and discouraged non-maintainer contribution to docs - notably fixes.

+1 for in-repo docs. Makes it much easier to keep up-to-date with code changes, as they happen, imo. 🙂

I am a 1st wisdom phase guy myself.

and allows docs to be changed atomically with code

This would be great for making the docs audit I do every major release less painful. It usually ends up taking me 3-4 days to audit 🤷

I would definitely encourage, as always, a wisdom thrash post-mortem if we switch back.

I think instead of saying "commits are hard" we should find out why and solve that problem. E.g. going through the test suite is annyoing, perhaps we can find out how to skip that, etc...

I would definitely encourage, as always, a wisdom thrash post-mortem if we switch back.

I am probably rewriting my recollection of events, but I remember the number one reason we changed to read me is that we needed versioning of the docs. The number two reason is that we wanted the docs to look prettier

but I remember the number one reason we changed to read me is that we needed versioning of the docs. The number two reason is that we wanted the docs to look prettier

You can clearly do both and have the primary docs source come from the repo as is being discussed now and as it was in the 1st phase of wisdom with the confluence plugin / doc targets.

The big problem here is can you turn off edits in Readme?

This has not been an issue for the generated reference docs. The few people with edit access to read me.com are trained to not edit directly. When users suggest an edit, we comment on their suggested change redirecting them to make a pull request

I was strongly against docs-in-repo, mostly because that led to them not being updated enough. Being able to edit ~inline as you read them in readme is powerful.

To be fair, without hard numbers, besides looking better, which is all due to Readme.com, I think the reason the docs are better in >80% territory, is because of Eric. Maybe I have a wrong idea though of where all that content has come from.

There are good theoretical arguments in favor of in-repo docs, but I have not seen them play out well in practice. Ease of modification seems to trump all other considerations in practice.

FWIW I would just be using the GitHub web UI for edits, so it's still relatively easy (to me) If anything id feel more empowered knowing my changes will be reviewed. I don't have high confidence in my prose.

ReadTheDocs (i.e. hosted Sphinx) covers a lot of the ease of modification difficulties that other in-repo docs solutions have, mostly because it’s a continuous deployment platform

Oh. That's cool, they are adding a new feature for collaboration kind of like google docs and git. That address is my biggest frustration: how hard it is to get reviews

Another bullet for in-repo docs, we can format and lint them. E.g. find stale imports, use good code style, etc...

See https://pantsbuild.slack.com/archives/C0D7TNJHL/p1654122151304319