docs: README update v0.3.0 #646

orpheuslummis · 2022-07-20T17:00:22Z

Relevant issue(s)

Resolves #146 and #187

Description

Updated README

Opens as draft PR to gather feedback from team first.

Preview it using this link (which I keep up-to-date to latest commit of PR):
https://github.com/sourcenetwork/defradb/blob/b58fee1c35ec6bba4ed293761759fd6acdff007c/README.md

Tasks

I made sure the code is well commented, particularly hard-to-understand areas.
I made sure the repository-held documentation is changed accordingly.
I made sure the pull request title adheres to the conventional commit style (the subset used in the project can be found in tools/configs/chglog/config.yml).
I made sure to discuss its limitations such as threats to validity, vulnerability to mistake and misuse, robustness to invalidation of assumptions, resource requirements, ...

How has this been tested?

Human reading.

README.md

fredcarle

I like it 🙂

jsimnz

one question, one change. Good stuff. Reads very well

jsimnz · 2022-07-28T23:11:00Z

README.md

-* [Early Access](#early-access)
-* [Installation](#installation)
-	* [Build](#build)
-* [Getting Started](#getting-started)
-	* [Add a Schema type](#add-a-schema-type)
-	* [Create a Document Instance](#create-a-document-instance)
-	* [Query our documents](#query-our-documents)
-	* [Interact with Document Commits](#interact-with-document-commits)
-* [Query Documentation](#query-documenation)
-* [CLI Documentation](#cli-documentation)
-* [Next Steps](#next-steps)
-* [Licensing](#licensing)
-* [Contributors](#contributors)
-* [Further Reading](#futher-reading)
-	* [Technical Specification Doc](#technical-specification-doc)
-	* [Design Doc](#design-doc)


question: Why get rid of the table of contents?

I thought: shorter is better, and cutting out the TOC would make it shorter lol

Github provides a TOC

Although it's probably not a well known feature

My preference is not to have a TOC and keep the README document short

IMO this adds value. I wouldn't prioritize shorter length over usefulness.

Let remember that this is a readme and not the full documentation. No TOC is quite ok here and I personally don't care about them on readme files. What I care about is basic usage how to and where to find more info.

IMO, TOC is metadata that can be inferred from the sections
Another example is getting the TOC automatically from vscode's Outline panel

jsimnz · 2022-07-28T23:17:09Z

README.md

-The current early access release has much of the digital signature, and identity work removed, until the cryptographic elements can be finalized.
+Set *nodeA* to actively replicate the "Article" collection to *nodeB*:
+```shell
+defradb client rpc addreplicator "Article" /p2p/<peerID_of_nodeB>


suggestion(blocking): This needs a full format. Not just /p2p/<peerID>

oh wow I missed that even after working on that package for a week...

I'm not currently sure we need the full address, i.e. it may be the case that /p2p/<peerID_of_nodeB> just works?

I'm not currently sure we need the full address, i.e. it may be the case that /p2p/<peerID_of_nodeB> just works?

It might work IFF the node in question has already previously been seen/connected to the given PeerID. Haven't tested locally so can't 100% confirm.

shahzadlone

Made some comments and suggestions, I was wondering though that the issue #146 mentioned about badges. I didn't see any new badges. I had some ideas:

Discord: https://img.shields.io/badge/Discord-7289DA?style=for-the-badge&logo=discord&logoColor=white
GoLang: https://img.shields.io/badge/Go-00ADD8?style=for-the-badge&logo=go&logoColor=white
Go Report Card: https://goreportcard.com/
CI build passing

We can do these later too, just checking that these aren't in scope?

One other suggestion I had is we could use collapsible (toggleable) sections if you were concerned about the length of the README.md .

shahzadlone · 2022-07-29T00:44:31Z

README.md

-#
-The DefraDB is a Peer-to-Peer Edge Database, with the interface of a NoSQL Document Store. DefraDB's data model is backed by [MerkleCRDTs](https://arxiv.org/pdf/2004.00107.pdf) for a multi write-master architecture. It is the core data storage system for the [Source](https://source.network/) Ecosystem, built with [IPFS](https://ipfs.io/) technologies like [IPLD](https://docs.ipld.io/) and [LibP2P](https://libp2p.io/) and featuring Semantic web3 properties. You can read the [Technical Overview here](https://docsend.com/view/mczj7ic4i3kqpq7s).
-
-Table of Contents


suggestion: keep TOC.

EDIT: Discussed on discord.

shahzadlone · 2022-07-29T00:45:44Z

README.md

-* [Early Access](#early-access)
-* [Installation](#installation)
-	* [Build](#build)
-* [Getting Started](#getting-started)
-	* [Add a Schema type](#add-a-schema-type)
-	* [Create a Document Instance](#create-a-document-instance)
-	* [Query our documents](#query-our-documents)
-	* [Interact with Document Commits](#interact-with-document-commits)
-* [Query Documentation](#query-documenation)
-* [CLI Documentation](#cli-documentation)
-* [Next Steps](#next-steps)
-* [Licensing](#licensing)
-* [Contributors](#contributors)
-* [Further Reading](#futher-reading)
-	* [Technical Specification Doc](#technical-specification-doc)
-	* [Design Doc](#design-doc)


IMO this adds value. I wouldn't prioritize shorter length over usefulness.

README.md

shahzadlone · 2022-07-29T01:34:18Z

README.md


-You can access the official DefraDB Query Language documentation online here: [https://hackmd.io/@source/BksQY6Qfw](https://hackmd.io/@source/BksQY6Qfw)
+## Query language documentation


question: Wonder if we need a small @explain request section like other main features.

I think this belongs in the documentation and not really in the readme. I already feel like there is too much in here.

We can debate how long the README should be. My opinion can definitely change, but I currently stand on the 'short and simple README' side which implies focusing on the simple exposition of core features only.

This PR improves the README but I believe it could be even better, i.e. shorter and clearer and more fun.

orpheuslummis · 2022-07-29T05:48:48Z

@shahzadlone badges as goal bumped to next update for v0.4: #686

shahzadlone

LGTM. Considering you will add the TOC with major headings.

orpheuslummis · 2022-07-29T06:22:42Z

@jsimnz ping

orpheuslummis added the documentation Improvements or additions to documentation label Jul 20, 2022

orpheuslummis added this to the DefraDB v0.3 milestone Jul 20, 2022

orpheuslummis requested a review from a team July 20, 2022 17:00

orpheuslummis self-assigned this Jul 20, 2022

orpheuslummis added the action/no-benchmark Skips the action that runs the benchmark. label Jul 20, 2022

sourcenetwork deleted a comment from source-devs Jul 22, 2022

orpheuslummis marked this pull request as ready for review July 22, 2022 14:06

orpheuslummis changed the title ~~docs: README update for v0.3.0~~ docs: README update v0.3.0 Jul 22, 2022

fredcarle reviewed Jul 25, 2022

View reviewed changes

README.md Outdated Show resolved Hide resolved

fredcarle reviewed Jul 25, 2022

View reviewed changes

README.md Outdated Show resolved Hide resolved

fredcarle approved these changes Jul 28, 2022

View reviewed changes

jsimnz requested changes Jul 28, 2022

View reviewed changes

orpheuslummis requested a review from jsimnz July 28, 2022 23:39

shahzadlone requested changes Jul 29, 2022

View reviewed changes

shahzadlone reviewed Jul 29, 2022

View reviewed changes

orpheuslummis requested a review from shahzadlone July 29, 2022 05:57

shahzadlone approved these changes Jul 29, 2022

View reviewed changes

orpheuslummis added 10 commits July 28, 2022 23:16

WIP

8e825c9

WIP

f6bbb4a

tweaks

53b524c

tweaks

a6e5792

further improvements

ff5d9b1

RPC example update

ea2e895

WIP

2400ca1

full p2p multiaddr

b3e8b0f

integrate Shaz's suggestions

443223e

TOC

d9dc38a

orpheuslummis force-pushed the orpheus/docs/README-update branch from 9b8ba32 to d9dc38a Compare July 29, 2022 06:16

jsimnz approved these changes Jul 29, 2022

View reviewed changes

rework of configuration section

5fd17aa

orpheuslummis merged commit f58e700 into develop Jul 29, 2022

orpheuslummis deleted the orpheus/docs/README-update branch July 29, 2022 07:01

orpheuslummis mentioned this pull request Jul 29, 2022

Include license TLDR in README #187

Closed

shahzadlone pushed a commit to shahzadlone/defradb that referenced this pull request Feb 23, 2024

docs: README update v0.3.0 (sourcenetwork#646)

7cffa24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: README update v0.3.0 #646

docs: README update v0.3.0 #646

orpheuslummis commented Jul 20, 2022 •

edited

Loading

fredcarle left a comment

jsimnz left a comment

jsimnz Jul 28, 2022

orpheuslummis Jul 28, 2022

orpheuslummis Jul 28, 2022

orpheuslummis Jul 28, 2022

orpheuslummis Jul 28, 2022

shahzadlone Jul 29, 2022

fredcarle Jul 29, 2022

orpheuslummis Jul 29, 2022

jsimnz Jul 28, 2022

orpheuslummis Jul 28, 2022

fredcarle Jul 29, 2022

orpheuslummis Jul 29, 2022

jsimnz Jul 29, 2022

shahzadlone left a comment

shahzadlone Jul 29, 2022

shahzadlone Jul 29, 2022

shahzadlone Jul 29, 2022 •

edited

Loading

fredcarle Jul 29, 2022

orpheuslummis Jul 29, 2022

orpheuslummis commented Jul 29, 2022

shahzadlone left a comment •

edited

Loading

orpheuslummis commented Jul 29, 2022


		You can access the official DefraDB Query Language documentation online here: [https://hackmd.io/@source/BksQY6Qfw](https://hackmd.io/@source/BksQY6Qfw)
		## Query language documentation

docs: README update v0.3.0 #646

docs: README update v0.3.0 #646

Conversation

orpheuslummis commented Jul 20, 2022 • edited Loading

Relevant issue(s)

Description

Tasks

How has this been tested?

fredcarle left a comment

Choose a reason for hiding this comment

jsimnz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shahzadlone left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shahzadlone Jul 29, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

orpheuslummis commented Jul 29, 2022

shahzadlone left a comment • edited Loading

Choose a reason for hiding this comment

orpheuslummis commented Jul 29, 2022

orpheuslummis commented Jul 20, 2022 •

edited

Loading

shahzadlone Jul 29, 2022 •

edited

Loading

shahzadlone left a comment •

edited

Loading