@rosano and I would like to discuss the state of RS websites and user-facing docs/info. If you’re interested in this topic, feel free to join us for this call! The more, the merrier.
Just to frame the discussion: I feel that there needs to be more clarity around who is the site for, and that it should be simpler to understand and contribute. I wanted to share my opinions about this and propose some possible solutions.
1 Like
Call on March 19, 2021 – Websites / docs
Participants: @rosano, @raucao
Issues
- People seem to have misconceptions about the project, sometimes don’t even recognize it as decentralized Web tech
- The layout of the site, the sparse wiki makes the project appear dated or inactive
- The site is trying to simultaneously speak to developers and users
- Perhaps too many places for information: site, wiki, forum, docs, readme, files
Think about
- Who is the site for?
- How to make it simpler to understand or target for specific audiences?
- How to increase adoption of the protocol?
Suggestions
- Standardize on markdown-like source files and present with a ‘readme style’
- eliminates complexity of having to think about layout, just edit text and the formatting will look great
- more modern presentation and ‘readme style’
- can be like readthedocs or github md files or discourse formatted text or http://zombie.js.org/ or Webnative SDK - Fission Guide
- Move the website/wiki to readthedocs or discourse or markdown files
- Focus on library
- communicates to developers that this is something they can integrate into their project
- Show code on front page
- communicates to developers how simple it is to get started
- Maybe show stars
- communicates the open source nature of the project, that it’s active, that there is a community
- Convert ‘my favourite drinks’ to todos
- feature a real world ‘usable’ example instead of a contrived one
Next steps
- Link to the library from the front page
- Show code in the readme
- Move remoteStorage protocol info from home page to a developers page
- Maybe use remotestorage.dev domain
- Look into discourse plugins for integrating with the website
- Make it clear that remotestorage.js is not remotestorage the spec
1 Like
I can confirm that the Discourse plugin listing is pretty messy…
Nonetheless, I was able to find a few plugins that might be helpful. I imagine a simple structure to start with: specify a ‘homepage’, else show the forum as is.
This one seems promising and recently active
It claims to be able to show forum topics on the landing page, but their example doesn’t seem to do that. I think it’s worth a try though, and would start here.
Other ones which might be useful for reference
I also noticed Category Page Plugin - plugin - Discourse Meta, which I imagine could be used to create an ‘app listing’.
1 Like