Hi! Now that in-repo docs have landed as an experi...
# developmenth
hundreds-father-404
06/14/2022, 1:09 AMHi! Now that in-repo docs have landed as an experiment (https://github.com/pantsbuild/pants/pull/15810), it's important folks don't directly save edits to Readme.com without updating GitHub. Those won't be persisted
@ancient-vegetable-10556 and I had the idea of tightening up the number of admins on Readme.com so that fewer people have to remember this gotcha. Thoughts?
b
bitter-ability-32190
06/14/2022, 1:36 AMI'm ok with jumping ship, so long as I can find a way to "rpeview" my local writing
b
busy-vase-39202
06/14/2022, 1:37 AMHow long would we be without admin access? If a couple days, fine by me. If a couple weeks, hmmm. Mayyyyybe...?
h
hundreds-father-404
06/14/2022, 1:40 AMThis would be indefinitely. Chris and I strongly suspect we will want to migrate to Sphinx pretty quickly, but we have not committed to the time investment needed for that
so long as I can find a way to "rpeview" my local writingTrue. I just finished doing my first substantial change, and it was very useful being able to hop into Readme.com's revised editor to preview. If we remove you from admin, then your only possibility is to use "Suggest edits" directly in Readme, and rely on an admin to port to GitHub So...maybe we don't take away privileges. Only, it's on you to remember you gotta update GH
b
busy-vase-39202
06/14/2022, 2:00 AMMost of my edits traditionally have involved creating new pages or rearranging existing pages. Losing access to do that directly would make headache for me + whichever of you ends up having to be my surrogate for those things.
busy-vase-39202
06/14/2022, 2:01 AMIf ReadMe had a way for non-admins to create or move pages, I'd be more open to downgrading privs. But afaik those are admin-only features.
h
happy-kitchen-89482
06/14/2022, 8:48 AMThe creating and moving pages directly in readme is pretty much what we're trying to avoid, IIUC?
b
bitter-ability-32190
06/14/2022, 1:46 PMYeah. Maybe it wasn't clear, @Carina C. Zona, but the point of this is that anyone can move and create docs using markdown files in repo. So it's just a PR away
👍 1
bitter-ability-32190
06/14/2022, 2:38 PMIt's all here: https://github.com/pantsbuild/pants/tree/main/docs
a
ancient-vegetable-10556
06/14/2022, 3:35 PMhttps://pantsbuild.slack.com/archives/C0D7TNJHL/p1655196505819709?thread_ts=1655168991.178269&cid=C0D7TNJHL
Yes, though you can create pages in git now.
b
busy-vase-39202
06/14/2022, 3:53 PMAll pages, not just API documentation pages?
b
bitter-ability-32190
06/14/2022, 3:55 PMYup!
h
happy-kitchen-89482
06/14/2022, 4:33 PMWell, the unversioned "custom pages" are debatable, there seems a lot less harm in keeping those in readme as the source of truth, at least for now. The ones that are oriented around devrel/marketing, as opposed to onboarding and using Pants
happy-kitchen-89482
06/14/2022, 4:33 PMIf we switch to sphinx then those would have to go along, but right now it's not clear that they have to?
b
busy-vase-39202
06/14/2022, 4:34 PMI'd love to have them out of readme. Its custom pages come with awkward restrictions that it would be nice to be liberated from.
h
happy-kitchen-89482
06/14/2022, 6:01 PMEven better 🙂
happy-kitchen-89482
06/14/2022, 6:01 PMAs long as you don't mind making changes in git. We can probably exempt some pages from code review, for faster turnaround.
a
ancient-vegetable-10556
06/14/2022, 6:01 PMThat’ll be a thing when we move to Sphinx
b
busy-vase-39202
06/14/2022, 6:01 PMYeah I love git.
a
average-vr-56795
06/17/2022, 11:29 PMShould the 'update the site' section of https://www.pantsbuild.org/v2.12/docs/release-process#step-2-update-this-docs-site now get folded into the release prep PR, now that docs are in-repo?
w
witty-crayon-22786
06/17/2022, 11:40 PMmm, yes. almost certainly.