Hello guys,
we’ve recently started to work on peercoin’s documentation.
The idea is to have a central place with all useful information about peercoin, covering from basic questions to deep technical explanations about the coin, the blockchain, their advantages and peculiarities over other blockchains/protocols.
Currently, most newcomers need to get to this forum or our chat channels in order to sane their questions, and I risk to say that 90% of those questions are always the same. Thats why its important to have a “unique” place to answer them and easily get updates as the protocol and the technology behind peercoin evolves. We’re also focusing into keeping it simple, fast and smooth, also on mobile devices. It will also be easy for users to share links/sections with other folks and spread knowledge about peercoin in a easy way.
Right now, we’ll be using this thread to discuss the content disposal (it will be only in english, for now), and everyone in the community is welcome to help.
The project will be written in Github’s Flavored Markdown (pretty close to what we use to write posts in this forum) and the website will be generated automatically using JavaScript.
I’ve been working with Kazzkiq on the design. This is just a concept, but what we have right now is very similar to the image below. It will say Docs rather than Wiki though…
While we are in the process of finalizing the layout of the documentation, we wanted to start the discussion about how exactly to organize the content. We don’t want to just start writing content in an unorganized way. I would like all of you think of this as if we were writing one long digital book about Peercoin. Our main goal right now is to figure out what chapters we’ll need and the best way to organize and order all that information from beginning to end in order for newbies to fully understand it.
We also need to think about it in marketing terms as well. It can’t all be dry information. Think about it as if it was one giant marketing piece for Peercoin. We want it to be interesting so that people will read and learn as much of it as possible. Using this documentation, we will be able to communicate everything about Peercoin that we want to. All those interesting discussions and facts about Peercoin are currently buried in our forum and chat and it’s our task to bring it all out in an organized way and show off Peercoin in the best light possible.
As you can see from the concept image, the left pane features the table of contents. There are both categories and subcategories. As you scroll down the list, each category will open up to reveal a list of subcategories. As an example, the first category should probably be titled Introduction and it would most likely feature information about the very basics of Peercoin, what year it was created, who developed it, the fact that it’s the very first implementation of proof-of-stake as well as a hybrid, stuff like that.
The introduction category would then open up into multiple subcategories, the first being titled “What is Peercoin?” This would give a beginner summary on what the purpose is behind the network, the problems with PoW only and how PoW/PoS solves those problems. Other subcategories below that one could be focused on Security or governance, etc…
Eventually after the introduction is complete, we would move on to the next main category, which would contain a whole new list of subcategory topics. It’s up to us to decide what that is. I would suggest moving onto downloading the client, how to use it, how to secure it, how to mint, how to troubleshoot problems (maybe have a separate troubleshooting category for that). Maybe next would be a category on everything about PeerAssets. Somewhere along the line we would have a category for advanced material, which would contain detailed explanations of the protocol, the code and refutations of myths about PoS, etc… We would need to rely more heavily on our developers to write the advanced section.
To start this process off we should first think about all the different topics that need to be written about and list them all. Then we take that list and organize it into a basic structure from beginning to end, keeping in mind the order a newbie may need to be presented information in order to fully comprehend it. Then we take the organization of categories and subcategories and start filling it in with content. We will know as we get into the writing whether something in the organization needs to be changed or added.
If you need help getting everything started, try checking out my Intro to Peercoin thread for ideas. We can then figure out how to expand it as well as what can be improved in its presentation…
There is also our current wiki which is being replaced…
We should not just copy and paste from this. Specific content can be reused if the situation calls for it, but we should work on our presentation of the content so that it’s easy to understand and ordered in a way that makes sense for a person just getting into crypto.
I believe the first and foremost thing we have to cover in the wiki is Proof of Stake. When I read the questions posted online by people, and consider what kind of readers the wiki are likely to attract, we will have to make this a fairly long and detailed post. It has to cover the most basics of basics. For example, it’s often you see people asking about PoS not even understanding that they have to own some coins and hold them in their wallet for minting. This is really a basic thing and most newcommers are not even aware of that.
After establishing these very fundamental and basic facts in a way that answers the questions of the newcommers, then we can start explaining the details of how PoS works, and how it has been implemented specifically in Peercoin, all while making it clear that Peercoin is a PoS/PoW system.
After explaining PoS and how it works, it would be great to start covering the economic ramifications of this, and make it clear to people how PoS ensures that Peercoin will never run into the same problems as Bitcoin has once Peercoin starts scaling, and we can also make it clear how PoS helps making PPC a superior form of “storage of wealth” compared to Bitcoin.
So we have decided with making a single “wiki” threat here on Peercoin talk, this thread will from now on be the primary place for us to talk about the development of the wiki and help each other out right?
In that case, I look forward to working with you guys from the start of July. Have a nice summer vacation folks!
I just updated my previously reserved post in this thread above.
Yes. This will be the main place to discuss maintenance of the wiki. Let’s try to field ideas here for feedback before just including them in the wiki, that way if there are mistakes or something can be rephrased in a better way, that can be pointed out by community members.
What happens to the old Wiki? Somebody should at least replace the old logo with the new one. And delete or update all the links (for example the chat room links to IRC (which in my oppinion is ok, but I think peercoin.chat is used more often in nower days, isn’t it?).
I imagine once the new wiki has enough content on it, we would just shut down the old one and change all links to the new one. The Wikipedia article should be updated though.
What’s wrong with the old wiki? Why do you want to replace it? Why not just update images and links and install the newest software (mediawiki) and maybe change the CSS?
And where is this new wiki you’re talking about?
And yes, I agree that Wikipedia’s article about Peercoin should be updated, as it leaves the reader thinking that Peercoin is dead, as it has only one last developer (if at all) − who is named Sunny King − and doesn’t mention any recent developments or projects around Peercoin.
I noticed, that the FAQ are very outdated (2014!!!). We should revise them. I.e. market cap 2017, tell something about version 0.6 (FAQ talks about version 0.2), tell something about the 1% reward, which @Peerchemist calls compensation instead of reward (should be explained!), explain the 0.01 PPC/kB (per kB, not per transaction, as the FAQ says!!).
As the FAQ is on the main site, it should be updated without delay, because this gives the impression, that Peercoin is dead (not maintained).
The old wiki isn’t really good enough by any standard. I don’t mean this as criticism of the person who put in a huge effort into writing this. But by all means, considering what information people seek when going to the wiki, a very short description on how to install the wallet and 1 paragraph of text saying that PPC has PoS isn’t really going to cut it if we want to advance Peercoin.
It’s been a while since I have really had to write lengthier forms of documentation, but hopefully over the next months we’ll get the wiki fleshed out and start writing a wiki that is worth visiting even for people not interested in Peercoin, but solely interested in how PoS works, and what consequences and security features it offers.
I think it is a great idea and looks nice, but it sounds very ambitious in its scope. It can be difficult to get the most knowledgeable people to find time to work on it, and even more difficult to keep it updated. With the current wiki very few developers contributed, and the one who probably contributed the most is no longer active.
As it will be on the main website it will also be seen as more official than a wiki. The vision of how Peercoin should be described has changed a huge amount over the years, and will likely change a lot in the future. At the end of the day it is just an interpretation and it is creating a huge amount of work attempting to have this explained fully and up to date.
I’m not trying to discourage, but think based on the experience with the current wiki it might be better to have a stripped-down version with just important info developers need to know, and maybe whitepapers etc.
If the homepage is overhauled that should help explain Peercoin’s key points from a marketing point of view.
What Peercoin is
* What is its supposed or possible use
How Peercoin works
* How PoS works
* What are the benefits of PoS, compared to PoW and other systems
* Comparison to other PoS coins: Differences, why is Peercoin better
History
What was the reason for Peercoin
Who developed it (background of the developers)
What caused the break in development
Who is continuing it, why, what changed?
Future (kind of rough roadmap), next goals
what is being worked on (really!)
what is planned
what is proposed
There could be several subarticles explaining techniques and algorithms. With many examples, please. So that everybody can see the advantages (or disadvantages?).
I believe things are different now though. We have a dedicated team working to make Peercoin great. Yes they are busy developing, but I’m sure they can find the time to look over our work and give suggestions from time to time. Before we were dealing with a time period where Sunny was the main developer, there was no team and interest was dwindling due to a shrinking market cap. It was a bad time to start a wiki.
It was also a complicated software to use, which is another reason people did not bother with it. I personally have used it only once or twice. I don’t care for the non-linear format of the software because it forces the user to click on lots of links in order to see all the content.
Anyway, I’m just trying to say that this time I think it will be different. If we’re going to commit to using this as a main source to educate people, then we’re going to have motivation to keep it updated. We did not really have this goal in mind with the previous wiki, so we didn’t keep up on it.
I’m not sure the vision has changed, but our understanding of the network has improved with time. Maybe things like the backbone argument and pushing transactions to off-chain networks can be left out as I don’t think there has been enough discussion on it from our developers, but there’s no reason why we can’t cover the basics of Peercoin which shouldn’t change, benefits of the hybrid approach over pure PoW, security, governance, etc…
We will have these topics covered on the main website yes, but that’s geared more for the type of marketing where text is limited. We still need a place where people can get a more indepth understanding of things.
I realise my previous post wasn’t very clear because I was kind of arguing two different points. I think my main point is that I disagree with having the docs as the “backbone” of the website as mentioned in chat. I think there should be separation between the material newcomers would see, and those with an extra interest would see. If there is no clear divide then I think it makes things very complicated and hard to maintain properly.
I’m not against having lots of documentation, but against having a kind of official grand narrative as the main piece on the website that everything is connected to. Maybe that’s not what you mean, but it’s what I interpreted it as.
If you think of the average person visiting the site, they will read the homepage to find out whether it is something that interests them, then click to find some basic guide on how to get started etc. In my opinion all of this basic information should be separate from the advanced information section that less than 1% of people will be interested in.
If they end up clicking on something on the homepage when they want to find out how to mint, but get taken to a page with a minting guide that is just above a 10-page essay on “the economics and governance of decentralised networks” or something, it will scare people away.
So I don’t think the plan should be to create the documentation, and then create the rest of the website based on that. I think everything the average person needs to know written in simple language should be the focus of the bulk of the website, with the rest hidden away in an advanced or developer section.
If there is too much emphasis placed on making people understand Peercoin then it makes it appear boring and elitist, something it has always suffered from.
You are overthinking this. We need docs/wiki and we have people interested in working on it so it is going to happen now, it is basically simple as that.
Alright, fair enough. My comments are less about having a new docs/wiki, and more about how I think the website should be overall. I think the way described here could require more work and maintenance than necessary in the long run, but since it’s only a starting plan it might not turn out like that.
Hey guys, the website should be here soon, but just so you know there is no reason to wait. We can start figuring out the navigation and order of content right now. This will need to be a community effort to write and maintain. I will try my best to be involved, but there are currently a lot of projects going on that are sucking up my free time. I hope everyone is aware that they can help contribute to this.
Also, in case you didn’t see it in the marketing thread, Kazzkiq posted a teaser screenshot, along with a sample website…
