I believe that all great projects were started with clear documentation. My project is a new open-source protocol that is searching to build a community around the concept of digital certificates that are secured by blockchain network. I see that our idea attract interest on the hackathons, meetups and tech chats, but it is essential to transmit those activities on the GitHub as well.
We have prepared Q&A page as well as simple project documentation http://docs.remme.io. But now I see a necessity to work more on our GitHub repository readme file. As I understood we need to add more about the problem that our code challenges, current features, contribution policy and left some info about the development team. I saw on the Internet a considerable number of advice about gifs, colorful buttons, and tables, but not sure that it wouldn't irritate our repo guests.
What else should we add on our core protocol page to make it closer to open source community and attract it to contribute to the project? I have added the link here:
Remmeauth / remme-core
Distributed Public Key Infrastructure (dPKI) protocol
REMME Core
How to run a node
The node was tested on Linux and macOS. Running on Windows may require significant modification of startup scripts.
Currently it is not possible to connect your own node to the test network. All nodes you will run will work on your own network.
You will need Docker and Docker Compose installed on your machine.
For an end-user
- Download the latest release from Releases section
(
<version_number>-release.zip
). Unpack it. - Start node: Open a terminal inside the unpacked folder and run
./run.sh
. - You can now use our RPC API. By default it is started on
http://localhost:8080. The API port can be changed in
config/network-config.env
file.
On the first run you will need to initialize the genesis block. To make
that just run ./run.sh -g
. This will generate a new key pair and
genesis block.
Flags available for run.sh
are:
-
-
scripts/run.sh
features…
-
Top comments (4)
I am currently writing cert-auth security docs at work, so I am really excited to see an OS project in the same domain.
I second Ben's suggestions of revisiting the README once a month as well as adding a high-level description of REMME Core. A few additional thoughts:
I am also curious to know how to use the product as a user. I parsed through the publicly available marketing and dev docs, but couldn't make the logical jump from the explainer video to the articles in the knowledge base. Is there a Getting Started guide that I failed to locate?
It was great tips. I collected them and included in upcoming changes. But here it is some changes that could be quickly implemented: github.com/Remmeauth/remme-core/is...
What do you think? Does that make our protocol more accessible? Maybe you can leave your comment directly in GitHub, so our contributors see them as well. I appreciate your help!
Oooh..it's so much clearer now! Left a few additional comments on the GitHub issue :)
I think documentation is best when it's iterated on. All the buttons and gifs in the world aren't going to keep a Readme from getting stale or becoming an afterthought after the first push.
So perhaps setting an internal goal to revisit the README at least once a month on top of accepting PRs.
Seeking feedback proactively also helps. Feel free to explicitly ask for feedback here as you iterate.
Feedback I'd give right away: Start with a What is Remme-core section in the Readme. Even if many people are landing there with context, many will not. Adding a high-level description at the top of the Readme could help a lot.