Documentation Update

[mrzmyr]

Hi there!

https://gun.eco/

🚀 How about an update of the documentation according to the following features?

• Structure: At first, I felt a bit lost where to get which information
  • Introduce new sitemap with terms like concepts, guides, reference (apis), integration, glossary, security
  • Separate general concepts from GUN concepts
  • Maybe move bigger examples to https://codesandbox.io (better maintenance, separation of styles and logic)
  • Streamline domains: Where do I look up the documentation? Wiki, gun.eco, gun.js.org?
• Code: The code seemed confusing to me sometimes
  • Example: on the one hand the pair functions is deprecated and on the other it is used on the same page in an example
  • Build solid guides for each tech stack (integrations)
• Design:
  • General readability (AA Level contrast, line heights, colors)
  • A unified way for translations (i.e. using https://weblate.org/en)
  • Links don't seem to work on FAQ
  • Work with streamlined visualization of the concepts
• Community get feedback from the community which pages need improvement and more
  • Use a thumb up/down functionality
  • Move to open source and provide a 'Edit this page' button for a PR
  • Give more advice for the beginners: What question do I ask to who and where? (https://chat.gun.eco)
  • Create a transparent roadmap (and maybe streamline the GitHub labels & milestones)

Examples of documentations:

• https://next-auth.js.org/getting-started/introduction
• https://www.prisma.io/docs/getting-started
• https://vercel.com/docs

Tools

• https://docusaurus.io/docs

Related issues

• https://github.com/amark/gun/issues/70

---

Just putting in some ideas coming from my first developer experience of Gun JS.

@amark, it's great to see so much work being done by the community & you.

[soulsam480]

I can help with setting up a brand new docs site with the current content. Please let me know if I should move forward or not. I also need the current docs in .md if it's possible to provide.

[davay42]

Current docs are automatically generated from this repo wiki. You can build right from there!

[amark]

@mrzmyr thanks so much, so sorry life has been very intense for me since the pandemic, and I'm super behind on lots of issues/pulls.

Only the sidebar is controlled by a PR... but hmm, I can't find the source link for it anymore @estebanrfp you know? @mrzmyr once we find that, would you edit the JSON that controls it with the new organization layout?

If it needs new content for it to work... unfortunately, I need people to contribute those articles 🙏 please, on integrations/etc.. I'm suppose to work on docs, but between my family emergencies, Secure Render, and the crisis of not losing 50M+ monthly active users in desperately getting things to scale even more, I'm very dry on time - I do have a whole series started, but it depends on Secure Render working. :/

You are right, pair is wtf, I think its being undeprecated, generally I encourage people to make any edit that would help, if it is wrong it'll get fixed later. But given docs are mostly 3 years old (tho APIs are stable), any edit is usually better than no edit.

Yes please, line-height fixes colors/translations, upvoting/onboarding/roadmap, etc. all that stuff just PR https://github.com/estebanrfp/gun.eco . He has done an amazing job, but we're all very desperate, low on time, volunteer, etc.

All content gets instantly automatically merged by GitHub via the wiki https://github.com/amark/gun/wiki/ , so no need to even fork.

I very much appreciate you spending the time to lay these things out. I agree! Wish I had more time, will merge what can be contributed! <3

[estebanrfp]

I had not read this, sorry for taking so long to comment, you should not fix what is not broken, knowing how it is built is a priority and finding the links will simply allow you to modify the side tree structure. https://raw.githubusercontent.com/gundb/gun-site/master/langs/menu-json-de.json https://gun.eco/docs/about-gun-eco#development - > I will be more attentive heh, I like to see the community wanting to help, I like it

[davidbludlow]

you should not fix what is not broken

I am sorry but this documentation is the most broken part of Gun, by far.

I tried to convince my boss for a year and a half to let us use Gun, but he absolutely refused, no matter how much it would have helped out our use case, no matter what demos I created. He refused because the documentation is so messy.

[davidbludlow]

How about you get a one-month subscription to GPT-4 (ChatGPT) and have it rewrite the documentation?

[davay42]

Hi! I've been helping with the certify docs and it seems to be very helpful to others building more complex apps with that. I agree that GUN docs are very messy and it took a couple of years for me to get proficient enough with Gun to make the https://gun-vue.js.org project running well. May be I can help with checking the GPT output or smth.

I also recommend reading the https://diataxis.fr/ to build more consistent documentation.

[davidbludlow]

I just discovered that https://github.com/Significant-Gravitas/Auto-GPT might be a more convenient mechanism for harnessing the power of GPT-4 to rewrite the docs. It can do things like do searches on the web for you to get knowledge that it doesn't already know and it can read/edit text files on your computer, according to your plain, human-language instructions.

[amark]

please do this! <3

(and bump, your boss would be boss if they donated to davay or you or someone to get this done. Elsewise, boss seems like kinda exploiting good natured open sourced projects, no? "we won't use open source unless they do more free labor for us" be super cool if he could pay you to help do the GPT thing or etc.)