Skip to content

Update README.md for v3#170

Merged
lthibault merged 2 commits into
v3from
docs/readme-improvements
May 12, 2021
Merged

Update README.md for v3#170
lthibault merged 2 commits into
v3from
docs/readme-improvements

Conversation

@lthibault

Copy link
Copy Markdown
Collaborator

I've taken the liberty of cleaning up the README a bit in preparation for v3. In particular, certain details of the installation process are no longer relevant with the upcoming switch to modules (see: #165, #166).

Additionally, I've made some rather opinionated changes with respect to "marketing" (or -- if you prefer -- with respect to the ordering of information by priority). I'm of the opinion that README's should first and foremost answer the question "what is this software, and is it for me?". The answers to these questions are somewhat scattered and buried below technical details, which IMHO only become relevant after the initial what/why questions have been answered.

My basic approach can be summarized as follows:

  1. In the heading, briefly what Capnp is, what go-capnp is, and why you might want to use it.
  2. If you're still reading, your next question is likely to be "how do I get it"? ==> installation
  3. If you successfully installed, your next question is "how do I start using it?" ==> getting started
  4. Once you have a minimal working example, you probably want to do something specific ==> API ref (godoc)
  5. Once you've mapped the docs onto a proof-of-concept in your head, you're wondering if there are caveats/gotchas ==> API compatibility notice + license

Feedback very much welcome.

P.S.: I added a couple of badges because nothing says "serious project" like badges. Devs love badges. 😝

@lthibault lthibault added this to the 3.0 milestone May 12, 2021
@lthibault lthibault self-assigned this May 12, 2021

@zenhack zenhack left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks reasonable to me; a couple comments in-line but nothing I'd block over.

Comment thread README.md
Comment thread README.md Outdated
@lthibault lthibault merged commit 9d559aa into v3 May 12, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants