Open JFWooten4 opened 1 month ago
Hi, @JFWooten4! Thanks for your continued attention and effort toward making our documentation as accessible as possible, for both readers and contributors! The particular example you bring up, is another instance of our content being "generated at build-time," although through a different means than it is for the OpenAPI docs in #991.
You bring up a really good point, though. The places where we are doing this kind of "trickery" isn't well-documented, and isn't obvious to the contributor how someone might go about just fixing a stinkin' period ๐คฃ.
I think we can accomodate a bit of both approaches 1 and 2, as you outlined above:
custom_edit_url
field available in the frontmatter for docs pages, so we can indeed specify what the URL should be for those pages. I almost forgot, but there's an existing issue to address this in the stellar-cli
repo: stellar/stellar-cli#1608 (there's also the potential of doing this programmatically, akin to how pnpm.io
's docs site does for its localized pages. this is achievable, but maybe more of a long-term approach, since it may indeed be complex to encompass the various "edit this page" cases we have.)CONTRIBUTING.md
file is a great effort! We could include in that file a section on "hard to edit" or "not obvious sources" or something like that to document as much of this kind of stuff as we can.
What problem does your feature solve?
Re @ElliotFriend in #991, there are a number of pages which are materially-difficult to edit. One such page has an obvious typo whereby there is no period at the end of a sentence, which might be caused by a lack of a functional
โ Edit this page
button. ๐ค Might we make it easier to rectify this and future typos for further contributions, and maybe even entice creative permissionless innovation?[^idea] At a minimum, the diction across the Guides might benefit from consistent "proper" syntax.[^idea]: Innovation in the sense that anyone could easily ready, ideate, and upgrade the docs. ๐ก
What would you like to see?
I can think of two solutions to this challenge. ๐ญ
Preferred Simplicity: ๐ Change the edit links to reference the actual base page via yarn build settings.
Technical Explainer: ๐ฉโ๐ญ Add
README
explainers to the direct pages to edit in GitHub for all instances[^ident] where this happens.[^dir][^dir]: One option could be to duplicate instructions for each placement in the parent directory of the rendered source host. ๐
[^ident]: This issue presumes we can identify all the places in the code where this phenomenon happens. As I understand it, Tyler originally migrated this guide, but others likely have a wholistic concept on the infrastructure side. ๐จโ๐ฉโ๐งโ๐ฆ
What alternatives are there?
We could leave it as challenging as it is to edit a relatively large amount of the Stellar docs. While this could be an easier approach, I think we can look at the state of XRPL's documentation to see just how well the closed-source approach works. Might we make crowdsourced documentation a staple of the network? ๐ค