Giters

dat-ecosystem-archive / docs

Documentation resources for dat and the surrounding ecosystem [ DEPRECATED - see https://github.com/hypercore-protocol/new-website/tree/master/guides for similar functionality. More info on active projects and modules at https://dat-ecosystem.org/ ]

Home Page:https://dat-ecosystem-archive.github.io/docs/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

link to this repository in the documentation

anarcat opened this issue · comments

commented

When I found a typo (#124) in the documentation, it wasn't clear to me how to fix it. It would be really great if there was a link to this repo so wannabe documenters like me could improve more easily. :)

commented

so #128 is a thing now, thanks! it makes the argument that:

any of:

  • "edit on github" corner ribbon/logo
  • a top-bar link along with "INSTALL" and "HOME" (which I don't think would show on mobile)
  • a link on the sidebar
  • a footer

feel like overkill. I like how simple the docs are currently. Maybe also a FAQ entry?

I'd state, for the record, that a ribbon is exactly what I was expecting, or at least a footer or sidebar. I like how Readthedocs manage this, with a little non-intrusive popup or link. For example, feed2exec has a "edit on gitlab" link on top. It might be too intrusive for your taste, but it's really useful for newcomers.

Having a single link in the FAQ or intro page has two downsides:

  1. it's hard to find: you need to know you can edit the page at all (which is not intuitive to most internet users) and then you need to want to find that information. too much friction which will keep away documenters
  2. the relevant page is hard to find. the link in #128 sends us to the docs repo - how do I know which page to edit? A direct link embedded in each page means less friction as well, as the visitor-would-be-documenter doesn't need to figure out how docs are built and where the relevant file is. As documentation becomes more complex, it becomes harder and harder to find the right document. Not everyone is trained in URL translation gymnastics that allows the brain to guess where the source file actually is. :)

Thanks for addressing this in some way anyways...

commented

Ya, I like that link on feed2exec. Think it does encourage user-driven maintenance to have a per-page link (that links directly to edit that page).