search

snarfed / bridgy-fed

🌉 A bridge between decentralized social network protocols
https://fed.brid.gy
Creative Commons Zero v1.0 Universal
562 stars 30 forks source link

Reorganize docs #1339

Open h-2 opened 1 week ago

h-2 commented 1 week ago

The documentation is super long and difficult to search/use. For example, I have been trying to find out how I can refresh my profile on the bridge server in BSky. If I search for "refresh", it leads me to:

Click the button on your user page. Bridgy Fed will refresh your profile and send it to any networks you're bridged into.

Unfortunately, the "user page" redirects to some site that is for bridging web-sites into the the fedi (which I have never done or wanted).¹

In general, I would recommend splitting the documentation into multiple different pages:

¹ I still haven't figured out how to find my "user page". I remember that the bot had a link to it, but that post has disappeared 🤷🏻

h-2 commented 1 week ago

Just putting the sections that exist in the top into separate pages would already help, I think 🙂

snarfed commented 1 week ago

Hmm, thanks for the feedback! You're absolutely right about finding user pages, that's https://github.com/snarfed/bridgy-fed/issues/1043.

Out of curiosity, could you say more about how splitting the doc into multiple pages would help?

Also, separating out sections for people on the fediverse vs Bluesky vs web sites definitely makes sense, that's what I (thought I) already did with the From the fediverse, From Bluesky, and From the web sections at the top. Did those not work for you?

h-2 commented 1 week ago

Out of curiosity, could you say more about how splitting the doc into multiple pages would help?

Well, if the page is long, people (i.e. at least me 😅 ) search for key-words. So I would do Ctrl+F and then enter a word like "refresh". It will land me somewhere in the document, and I have no clue if whatever is written there actually applies to my use-case. In this case, it was redirected to a page that is only for "web-sites", so I can back and assume that this was the wrong place, so I keep on searching...

Also, separating out sections for people on the fediverse vs Bluesky vs web sites definitely makes sense, that's what I (thought I) already did with the From the fediverse, From Bluesky, and From the web sections at the top. Did those not work for you?

Those are really good, but as soon as I have clicked on one thing, I am somewhere in the document and after a bit of scrolling, I am lost and need to go back up...

It would be better if those section were separate pages. Alternatively, having a floating table-of-contents on the left which highlights which section you are in, would also improve the situation.