stellar / stellar-docs

Documentation for Stellar
https://developers.stellar.org
Apache License 2.0
63 stars 125 forks source link

๐Ÿ“ Punctualize, stylize CLI Guide #1013

Open JFWooten4 opened 1 month ago

JFWooten4 commented 1 month ago

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. ๐Ÿ’ญ

  1. Preferred Simplicity: ๐ŸŒŒ Change the edit links to reference the actual base page via yarn build settings.

  2. 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? ๐Ÿค

ElliotFriend commented 1 week 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:

  1. There is 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.)
  2. I think the start you've made to a 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.