README update

README.md

@@ -1,83 +1,146 @@
-# libp2p Docs
+<p align="center">
+<img align="center" src="static/images/libp2p-docs-logo.png" width="615">
+</p>
+
+<div align="center">
+
+[![Made by icon.](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](https://protocol.ai/)
+[![Project icon.](https://img.shields.io/badge/project-libp2p-lightgrey)](https://libp2p.io/)
+[![Build status icon.](https://img.shields.io/circleci/project/github/ipfs/ipfs-docs/master.svg?style=flat-square)](https://circleci.com/gh/ipfs/ipfs-docs)
+![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)
+[![Discuss](https://img.shields.io/discourse/https/discuss.libp2p.io/posts.svg?style=flat-square)](https://discuss.libp2p.io)
+</div>
+
+<!-- TOC -->
+- [Overview](#overview)
+- [Contributing content](#contributing-content)
+- [Running locally](#running-locally)
+- [Configuration guide](#configuration-guide)
+  - [Static site generator](#static-site-generator)
+  - [Automated deployments](#automated-deployments)
+  - [Translation](#translation)
+- [Primary maintainers](#primary-maintainers)
+- [License](#license)
+<!-- /TOC -->
+
+---
 
-Home of https://docs.libp2p.io
+## Overview
 
----------------
+libp2p is a modular framework that encapsulates an evolving set of specifications for peer-to-peer networking. What started as the networking component that enables IPFS turned into a general-purpose framework to deliver a modular, peer-to-peer networking stack of protocols that are transport agnostic, flexible, reusable, and easy to upgrade.
 
-This repo is used to:
+libp2p enables interoperability between applications, resilient applications, and advanced networking features like decentralized publish-subscribe or advanced data structures like distributed hash tables.
 
-1. Organize documentation work across the libp2p project.
-2. Host the documentation website for libp2p. It gets published to IPFS and made available at https://docs.libp2p.io/.
+## Contributing content
 
-Check the [issues](https://github.com/libp2p/docs/issues) for updates.
+The documentation site contains several different kinds of content. We’d love ❤️ your help with any of it:
 
+1. **Introductory overviews**: this lives in `content/introduction`. If you spot a problem or have improvements, please post an issue or PR.
 
-## Overview
+2. **Guides, examples, and tutorials**: Most examples currently live in other repositories, like [js-libp2p examples](https://github.com/libp2p/js-libp2p/tree/master/examples). If you have thoughts on integrating them better, please file an issue. If you have feedback on individual examples or want to add a new one, please file an issue or pull request on the relevant repository. If you have ideas for guides or tutorials, they belong here! Please propose them in an issue here before creating a pull request.
 
-libp2p documentation currently has several acute problems:
+3. **Concept guides**: Concept guides are intended to present a brief overview of libp2p-related concepts. They live in the `content/concepts` folder and should strive to answer:
 
-- There is **no clear introduction to the overall idea of exactly how libp2p works and what it’s doing.**
-- libp2p has **lots of new concepts** that are just very different from the web technologies people know today.
-- **Docs are inconsistently located** and spread across a number of repos people have to hunt through.
-- Clear, **standard API docs** are not always available.
-- **Hunting through GitHub is hard.** (Which repos have docs? Where in the repo are they? Which projects are important and how do they relate to the others? Which repos and docs are up-to-date?)
+    - **What** is this?
+    - How does it **relate** to the rest of libp2p?
+    - How can (or should?) you **use** it? (This can often vary by implementation
+    - **Where** do you go to learn more?
+    - What is the **current state** of affairs?
 
-We aim to solve some of these problems through a documentation site (the source of which is in this repo) and others through organizing work, conventions, and practices across project repos (managed in the issues here).
+    See a list of concepts we need help with by [checking the issues](https://github.com/libp2p/docs/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3Acontent+concept).
 
-## Contributing content
+4. **Reference documentation**: Please see the issues in this repository for current activity around reference/API documentation.
 
-The documentation site contains several different kinds of content. We’d love ❤️ **your** help with any of it:
+5. **Community**: If there are missing community links, feel free to file an issue or pull request,
 
-1. **Introductory overviews.** This lives in `content/introduction`. If you spot a problem or have improvements, please post an issue or PR.
+This repository is also a website; we could use your help with design and technical features (interactive examples, better syntax highlighting, scripts to pull in content from other repositories, etc.) in addition to writing. To get a sense of what we could use help on, check the [issues](https://github.com/libp2p/docs/issues). If you decide to work on one, please post to the issue to let us know!
 
-2. **Guides, examples, and tutorials.** Most examples currently live in other repos, like [js-libp2p examples](https://github.com/libp2p/js-libp2p/tree/master/examples). If you have thoughts on how to better integrate them, please file an issue here. If you have feedback on individual examples or want to add a new one, please file an issue or PR on the relevant repo. If you have ideas for guides or tutorials, they belong here! Please propose them in an issue here before creating a PR.
+Before posting a pull request with your changes, please check [our style guide](https://github.com/ipfs/community/blob/master/DOCS_STYLEGUIDE.md) and [contributing guide](https://github.com/libp2p/community/blob/master/CONTRIBUTE.md).
 
-3. **Concept guides.** Concept guides are intended to present a brief overview to libp2p-related concepts that might be new to people. They live in the `content/concepts` folder and should strive to answer:
+Finally, let’s work together to keep this a respectful and friendly space. Please make sure to follow our [official code of conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).
 
-    1. **What** is this?
-    2. How does it **relate** to the rest of libp2p?
-    3. How can (or should?) you **use** it? (This can often vary by implementation)
-    4. **Where** do you go to learn more?
-    5. What is the **current state** of affairs?
+## Running locally
 
-    See a list of concepts we need help with by [checking the issues](https://github.com/libp2p/docs/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3Acontent+concept).
+The site uses a `MakeFile` to handle the site building procedure.
 
-4. **Reference Documentation.** Please see the issues in this repo for current activity around reference/API documentation.
+Build the optimized site by running:
 
-5. **Community.** If there are important missing community links, file an issue or PR here!
+```bash
+make
+```
 
-This repo is also a website, which means we could also use your help with design and technical features (interactive examples, better syntax highlighting, scripts to pull in content from other repos, etc.) in addition to writing. To get a sense of what we could use help on, check the [issues](https://github.com/libp2p/docs/issues). If you decide to work on one, please post to the issue to let us know!
+To create a production build, run:
 
-Before posting a PR with your changes, please check [our styleguide](https://github.com/ipfs/community/blob/master/DOCS_STYLEGUIDE.md) and [contributing guide](https://github.com/libp2p/community/blob/master/CONTRIBUTE.md).
+```bash
+make build
+```
 
-Finally, let’s work together to keep this a respectful and friendly space. Please make sure to follow [our code of conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).
+> This requires hugo & ipfs on your PATH
 
+You’ll find the final static site in the `public` directory.
 
-## Building the Docs Site
+To serve the static files, run:
 
-### Build and Run the Site
+```bash
+make serve
+```
 
-* In the root directory, run `make dev`
-* Load http://localhost:1313 in your web browser
-* Edit and add things!
+> This requires hugo & ipfs on your PATH
 
-To create a production build, run `make build` instead. You’ll find the final static site in the `public` directory.
+Preview the site at http://localhost:1313.
 
-### CI and publication
-
-This site deploys through [Fleek](https://app.fleek.co) to https://docs.libp2p.io
+Run the following `make` command in the root directory to start a hot-reloading dev server:
 
-## FAQ
+```bash
+make dev
+```
 
-### Why is this is a static site?
+> This requires hugo on your PATH
 
-We believe in hosting libp2p's documentation on IPFS, and that’s much easier when the content is static.
+Preview the site at http://localhost:1313.
 
+To add an preview the site on IPFS, build the site in the root directory by running:
 
-## License
+```
+make deploy
+```
+
+> This requires hugo & ipfs on your PATH
+
+See the `Makefile` for the full list of `make` commands, or run `make help` in the project root. 
+
+> You can pass the environment variable `DEBUG=true` to increase the verbosity of your chosen command.
 
-All software code is copyright (c) Protocol Labs, Inc. under the **MIT license**.
+## Configuration guide
 
-Other written documentation and content is copyright (c) Protocol Labs, Inc. under the [**Creative Commons Attribution-Share-Alike License**](https://creativecommons.org/licenses/by/4.0/).
+### Static site generator
+
+The libp2p documentation site uses [Hugo](https://gohugo.io/) as a static site generator, 
+making it easy to serve and host the static files on IPFS. In particular, the site uses 
+the [Hugo Learn theme](https://learn.netlify.app/en/) to present the libp2p documentation.
+
+### Automated deployments
+
+When opening a pull request, CI scripts will run against your feature branch to test your changes.
+
+The CI/CD production workflow builds on the `master` branch and deploys the documentation site on [fleek](https://fleek.co/). It reflects the latest commit on `master` and publishes at [https://docs.libp2p.io](https://docs.libp2p.io).
+
+### Translation
+
+Please stay tuned for the steps to translate the documentation.
+
+## Primary maintainers
+
+- [@DannyS03](https://github.com/DannyS03): primary contact, project organization & technical writing
+- [@mxinden](https://github.com/mxinden): libp2p steward, primarily rust-libp2p
+- [@marten-seemann](https://github.com/marten-seemann): libp2p steward, primarily go-libp2p
+- [@MarcoPolo](https://github.com/MarcoPolo): libp2p steward, primarily go-libp2p
+- [@jennijuju](https://github.com/jennijuju): documentation management
+- [@p-shahi](https://github.com/p-shahi): libp2p project management
+- [@BigLep](https://github.com/BigLep): interplanetary management and supervision
+
+## License
 
-See [LICENSE file](./LICENSE) for details.
+All software code is copyright (c) Protocol Labs, Inc. under the **MIT/Apache-2 dual license**. 
+Other written documentation and content are copyright (c) Protocol Labs, Inc. under the 
+[**Creative Commons Attribution-Share-Alike License**](https://creativecommons.org/licenses/by/4.0/).