Move to a wiki
martinheidegger opened this issue · comments
In the irc/gitter chat @mafintosh brought up that it would be useful to have a wiki for our docs. I enabled the github wiki in this repo as a test and think we could easily move the existing markdown files to the wiki and update the static site generator to use the wiki files for the homepage.
it was brought up that ethereum's github wiki is excellent, here are some links from that
- contrib guidelines/tricks https://github.com/ethereum/wiki/blob/master/CONTRIBUTING.md
- article example https://github.com/ethereum/wiki/wiki/Kademlia-Peer-Selection
From my experience with the Github Wiki it's a lot better to structure and work with, if you clone it as a Git repository and edit locally: https://help.github.com/en/articles/adding-or-editing-wiki-pages#adding-or-editing-wiki-pages-locally
It then allows to add files in subfolders for example: https://gist.github.com/subfuzion/0d3f19c4f780a7d75ba2
Seems like you can do even more: https://grantwinney.com/5-things-you-can-do-with-a-locally-cloned-github-wiki/
Hey all.
Happy to do whatever people think is good. Would like to wait to hear @RangerMauve and @joehand and @whoisgina, who, along with myself, have created much of the content in this repository. It is built off of tech similar to what other more popular projects are using.
The github wiki experience isn't as easy to navigate quickly, and the presentation of the content requires loading all of github.
The current site, on the other hand, is a simple static site with minimal Javascript. It also has built in i18n translation support, which we want to flesh out this year.
What kind of content would be on the wiki that wouldn't be on the docs site? Where to draw the line?
I think it's important no matter what technology to have overarching documentation for all the disparate modules in one place. Otherwise it's unclear where the docs might be for a particular topic that someone is looking for.
If they're not in the same place it would be nice to have them linked. For example, if all the details and gotchas about the dht are in the wiki or in the hyperswarm/dht module, it would be great if someone coming in from the internet typing "documentation dat" to be able to find it.
Can we think through:
1.the goals of this repo
2. the audiences
3. who will maintain this repo
4. the links between it and other repos?
If we want to increase the success of developers working with the tools, then let's figure out how to best do that :)
Why a wiki? Who is the intended audience?
My questions are similar to Karissa’s:
- What’s in the wiki? The same content as
docs.datproject.org? - Is the intent to replace the current docs site or just mirror the content?
- Are you aiming to improve the experience for the people editing the docs or for the people reading them?
The most important question for me is whether using a wiki would make it easier to keep docs up to date or just add another layer of cognitive load for maintainers.
Part of the work I’m doing this summer is consolidating all existing documentation so that I can integrate it directly into a new website for the Dat Project this fall. So, I'm leery of adding any new services or duplicating existing content.
I agree with Karissa that it’s difficult to navigate GitHub wiki pages. I don’t think that GitHub is a good solution for any public-facing documentation. I’m strongly favoring Docusaurus (or something similar) right now because:
- It’s popular, well-supported, and in active development.
- Support for i18n and language switching (when you switch the language of those Ethereum pages only the content of the page is translated; no UI elements or navigation items come along for the ride).
- More accessible (imo, after a quick spin through with my tab stop and screen reader tools).
- Generates a static site which would be easy to share with Dat.
- Most importantly: it’s already done!
What’s in the wiki? The same content as docs.datproject.org?
Is the intent to replace the current docs site or just mirror the content?
In my thinking it would be the other way around: docs.datproject.org would mirror the wiki, showing the current navigation.
Are you aiming to improve the experience for the people editing the docs or for the people reading them?
Keeping the experience for people reading the docs the same but improving the experience for people writing the docs: Resulting in more/better docs?