DEV Community

Andriy Fedotov
Andriy Fedotov

Posted on

Documentation as a key to the strong tech community

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

CircleCI Docker Stars

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

  1. Download the latest release from Releases section (<version_number>-release.zip). Unpack it.
  2. Start node: Open a terminal inside the unpacked folder and run ./run.sh.
  3. 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)

Collapse
 
amrutaranade profile image
Amruta Ranade

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:

  • It might be helpful to have a link to the explainer video (youtube.com/watch?v=9APHeHRmrGw). The video will help set the context and orient the user by explaining the end-problem that REMME aims to solve.
  • The next logical step is a brief overview of the architecture of the product and where/how Core fits into it.
  • Then a brief overview of Core's architecture/design would be helpful, followed by a list of features in dev and opportunities for contributions.
  • Then move on to the tactical part: a section for prerequisites that has a bullet list of requirements (macOS, Linux, Docker, etc.)
  • I am unsure of what the "For end-users" section refers to. My instinct tells me this is the installation section that developers and contributors could benefit from as well (they could try out the product from the user's perspective before figuring out how/what to contribute). If yes, the section could be renamed as "Install REMME Core". (I am utterly confused by how Core could be installed as a stand-alone application and how it fits into the rest of the components, but I attribute this confusion to my lack of technical know-how of this project).
  • This could be followed by the "For developers and contributors" section.

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?

Collapse
 
andrii_fedotov profile image
Andriy Fedotov

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!

Collapse
 
amrutaranade profile image
Amruta Ranade

Oooh..it's so much clearer now! Left a few additional comments on the GitHub issue :)

Collapse
 
ben profile image
Ben Halpern

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.