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

REMME is a blockchain-based protocol used for issuing and management of public keys to resolve issues related to cybersecurity, IoT connectivity, data integrity, digital copyright protection, transparency etc.

Remme core is built on Hyperledger Sawtooth platform, allowing to be flexible in language choice during the development process.`Remme core exposes application programming interface based on RPC API.

Remme also supports JS and .NET programming libraries that wrap its application programming interface, so that you could easily embed the protocol in your project.

🔖 Documentation

🔖 Architecture overview

🔖 Docs & tutorials

🔖 REMME use case for IoT

🔖 Blog & talks

How to build on REMME Core

1. REMChain is one of the components of our solution and a basic layer of our distributed Public Key Infrastructure — PKI(d) protocol. In a nutshell, it’s a multi-purpose blockchain that acts as a distributed storage for a certificate’s hash, state (valid or…

View on GitHub

Comments

[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?

[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!

[Amruta Ranade]

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

[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.