Feedback on Replacing Peercoin's Wiki Software

Me and @peerchemist had previously talked about replacing the software used for Peercoin’s wiki. Currently it uses media wiki and can be found at the link below, although there seems to be a certificate issue preventing the site from opening. @Fuzzybear still runs this wiki…

https://wiki.peercointalk.org/

We would need wiki software that is easy to be styled, so it can fit in with the rest of Peercoin’s color theme and graphics. It should also be based in GitHub so that it makes it easy for people to submit changes. The new wiki would be located at the following URL…

https://wiki.peercoin.net

We had previously spoken of two pieces of software. The first is what @CoinGame and @Ben had setup and were using for all of Nu’s documentation. You can find a link to that here…

https://docs.nubits.com/

It doesn’t seem to have subcategories though, which would make organization of various topics easier. Peerchemist had also pointed me to this software which rocket.chat uses for their wiki, which does have subcategories…

https://rocket.chat/docs/

I just wanted to get a discussion started on this and to see what people thought about it. We will need to get something setup soon because we’ll need to start documenting our protocol as well as info on PeerAssets and other things. We’ll need an organized resource center that we can point people to. Directing people to the forum to search for info they need is not very helpful or convenient.

Hi all,

Sorry yes the SSL cert expired for the *.peercointalk.org and I need to provide verification docs again from me to renew it sry :frowning: , i’ll see if i can put up a self signed cert for it as temp so wiki does not have the security issue.

But yes I am all in favour of replacing the wiki software. Personally I probably prefer the Nubit style wiki as I prefer the layout of the left hand side more with the links and from those pages you can make links to subpages or navigation pages about that category maybe?

Fuzzybear

The Nu documents is a very customized Jekyll site. We couldn’t find any free options that provided the kind of experience and look that we wanted. It would be fairly easy to fork the Nu docs, and customize them any way you choose. Though it does require quite a bit of overhead, and i’m not sure it would be appropriate for volunteers. Though that was quite some time ago and you may be able to find some newer fancier open source solutions that fit your needs, such as the ones you listed above.

1 Like

We need something that can work with git repo as a backend. So any change goes through moderated git repository. I’ve seen solutions like that. I think rocket.chat uses something like it for their documentation site.

Like @CoinGame suggests, Jekyll can be fully managed and served on github.
So forking Nu’s documentation might be a good idea.

We could use peercoin.github.io/docs

Slate

I personally think Slate is a strong candidate. Its beautiful, simple, elegant, uses markdown and can run directly on Github Pages. The downside? It uses Ruby to generate the docs (who uses Ruby nowadays?).

Live example: https://lord.github.io/slate/

(Slate docs example)

Flatdoc

Flatdoc is also a nice option. Not as complete as Slate, its true, but still extremely fast, responsive, supports markdown and can be easily generated and deployed on Github Pages.

Live example: http://ricostacruz.com/flatdoc/#flatdoc

(Flatdoc docs example)

GitBook

Gitbook is more like a mix of blog + books + documentation. While I do not think it would be the best option for documentation, I still think it can be pretty useful in the future for creation and propagation of guide-like “books” related to Peercoin (or PeerAssets). It lets you write content that is more complex than a blog post, but still appealing in terms of marketing and gracefully separated into easy-to-follow chapters.

Live example: http://redux.js.org/docs/introduction/

(GitBook docs example)


All of those seems to be easily stylized, easily deployable and extremely simple to write content into.

As there is interest from some community members to start contributing, I believe it is time to move forward with this.
I’ve initialized the repository, https://github.com/peercoin/wiki

We need to agree on format of the wiki first.
Perhaps each article should just submitted as another Markdown file?

I’d like to look through these options when I wake up in about 8 hours. Has anyone else looked through them yet? Does anyone have a preference and reasons why they choose it over others? Please post what you think. If there is no participation then we’ll just have to pick one and run with it.

I like Slate and Flatdoc. The menus look clean, I like that they’re fixed instead of the endless scroll bar for the rocket.chat one as an example. I also prefer the darker theme of Slate. I’m not familiar with either but whichever one is chosen would need to be easy to manage/maintain.

Just so everyone knows I looked over the options last night as well as a lot of the example sites. I really like Slate the most. I’m currently in the middle of trying to create a concept image for how I think it should look. That’s usually what I do to try and figure out the design of something. I’m not sure if I’ll be done it today or tomorrow, but I just wanted to let everyone know that I’m working on it.

Ok, here is the concept image I created in paint of what a Peercoin Slate wiki would look like…

Full-Size Image

I tried to get the concept as close as possible to what I wanted it to look like. I wanted the Peercoin banner logo and site navigation at the very top with the actual wiki right below it.

The actual content of the image won’t make any sense because I took different pieces from different example sites and just changed the colors to match Peercoin’s style. I’ll go through the examples I borrowed from to make this…

https://docs.dwolla.com/#introduction

This example takes the navigation on the left side of the screen. In my altered version I’ve changed the colors to match similar to peercoin.chat. The overall navigation is dark gray with the open subcategories in a lighter gray. The actual topic selected is Peercoin green.

https://developers.cimediacloud.com/

In this example I took the far right side where the code is listed. I’m not exactly sure if this side will be needed for our purposes, but @hrobeers had mentioned before about documenting our protocol. If anything, it could possibly be used for that. Pieces of code from the protocol would be displayed on the right side while the content in the middle would explain in detail what that part of the code does.

I also used the content in the middle from this example. The font used does not necessarily have to be the same in the final product as this is just an example.

https://docsv2.dwolla.com/#introduction

Just in case the far right side is not needed for any code, this example shows what a wiki looks like without it. There is only just a white background on the right and the main content in the center of the page. Another piece I like about this example is that if you hover your cursor over the navigation buttons on the left side, they turn a different color. The same is true with peercoin.chat and hovering over the various channels. They turn an even darker gray. It’s not in the concept, but that’s exactly what should happen in our version.

https://developers.coinbase.com/api/v2#authentication

Nothing from this example is in the concept image, however there is something that I liked. In the left navigation pane I like how all the different pieces of content are grouped into categories. The category titles are bolded and help organize the content while the subcategories are normal non-bolded font. The sub-categories can even be split down into sub-sub categories for even more organization. Peercoin should do the same, so content is very easy for people to find.

Other thoughts about the concept: The green text on the right side is the wrong color and should probably be our Peercoin green font. Any blue links in the center content should also be the same Peercoin green. It was mentioned that Ruby might be a problem, but @sigmike specializes in Ruby in case we need any help.

What do you guys think?

3 Likes

Did you have a chance to fix the SSL cert? I know a new wiki is in the plans but have you looked into using letsencrypt temporarily? For now I changed the wiki link on peercoin.net to go to http so people can still access the content. I don’t know if there’s a way to hide the login button on the actual wiki otherwise so people don’t try to log in using plain text.