Readme chapter

manuscript/documentation/01-readme.md

@@ -1,29 +1,101 @@
 # README
 
-A project **README** is often the first thing people see at npm or GitHub when they find the project. The project's site is another entry point. Sometimes these use the same content or sometimes you might design a separate landing page for the site.
+A project **README** is often the first thing people see when they find the project. The project’s site is another entry point. Often a site is generated from a README file content with nice CSS.
 
-A good README can "sell" the project to a potential user. A badly written one can scare users away even if the functionality is solid. Sometimes the developers don't understand this and as a user you may have to dig beyond the surface to find the value.
+A good README can “sell” the project to a potential user. A badly written or formatted one can scare users away even if the library would solve their problem and has a good API.
 
 ## What a README Should Contain
 
 README should describe briefly what the package is about before delving into the details. A high level overview of the functionality and why the package was developed is enough. By doing this well, you save time as it will either attract people that have the same problem or make them understand the package isn't something they need.
 
-Examples convey how to use the package. Ideally you are able to run them as tests. Besides making sure the examples work, this is also a rough way of **acceptance testing**. It's a good idea to start designing a package by writing the README. This forces you to think about the API carefully from the user point of view and come up with a design you can document easily.
+Examples convey how to use the package. Ideally you are able to run them as tests or generate documentation from the real source code. Besides making sure the examples work, this is also a rough way of **acceptance testing**. It’s a good idea to start designing a package by writing the README. This forces you to think about the API carefully from the user point of view and come up with a design you can document easily.
 
-If the package is small, you can include its entire API documentation in the README. For bigger packages it can make sense to push the information below separate documents and host the information on the package site. Too big a README can also mean you have to split your package up somehow. This is where the **monorepo** approach may come in handy.
+If the package is small, you can include its entire API documentation in the README. For bigger packages it can make sense to split the documentation into several smaller documents. Too big a README can also mean you have to split your package up somehow. This is where the **monorepo** approach may come in handy.
 
-You should include licensing information at the end of the README as it's a good convention to have. You can also mention sponsors and maintainers there so they get the visibility they have earned.
+You should include licensing information at the end of the README: people will want to know if they are allowed to use your library in their project. You can also mention sponsors and maintainers there so they get the visibility they have earned. Links to contribution guidelines and code of conduct is another good idea to make them more visible.
 
-## Automating README Fields
+## Automating README
 
-TODO: markdown-magic + pulling meta from package.json
+### Table Of Contents
 
-TODO: TOC generation - `npx markdown-toc -i Readme.md`
+If your README is big, table of contents will give readers a quick overview of what’s inside. With [markdown-toc](https://github.com/jonschlinkert/markdown-toc) you can keep links in a table of contents correct and up to date:
+
+```markdown
+## Table of contents
+
+<!-- To update run: npx markdown-toc --maxdepth 2 -i README.md -->
+
+<!-- toc -->
+
+- [Installation](#installation)
+- [Upgrade from v0.4](#upgrade-from-v04)
+- [Example](#example)
+- [More examples](#more-examples)
+- [Custom blocks](#custom-blocks)
+- [Available webpack blocks](#available-webpack-blocks)
+- [Helpers](#helpers)
+- [Shorthand setters](#shorthand-setters)
+- [Third-party blocks](#third-party-blocks)
+- [Design principles](#design-principles)
+- [FAQ](#faq)
+- [Like what you see?](#like-what-you-see)
+- [License](#license)
+
+<!-- tocstop -->
+```
+
+T> You can also use Markdown Magic to generate table of contents — see below.
+
+### Including External Files
+
+[Markdown Magic](https://github.com/DavidWells/markdown-magic) is a tool to include external files or any dynamic data.
+
+Let’s install Markdown Magic:
+
+```bash
+npm install --save-dev markdown-magic
+```
+
+Add a new script to your _package.json_:
+
+```json
+"scripts": {
+  "docs": "md-magic --path '**/*.md' --ignore 'node_modules'"
+},
+```
+
+By default you can use one of these _transforms_:
+
+* CODE — includes code from a file;
+* REMOTE — content of a remote files;
+* TOC — table of contents.
+
+For example, to include code from a file:
+
+```markdown
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./relative/path/to/code.js) -->
+This content will be dynamically replaced with code from the file
+<!-- AUTO-GENERATED-CONTENT:END -->
+```
+
+And now run `npm run docs` every time you want to update your Markdown files.
+
+You can create [your own transforms](https://github.com/DavidWells/markdown-magic#adding-custom-transforms) or use plugins:
+
+[github-contributors](https://github.com/DavidWells/markdown-magic-github-contributors) — GitHub contributors list;
+[install-command](https://github.com/camacho/markdown-magic-install-command) — install command  with `peerDependencies` included;
+[subpackage-list](https://github.com/camacho/markdown-magic-subpackage-list) — list of all subpackages (great for projects that use Lerna);
+[package-scripts](https://github.com/camacho/markdown-magic-package-scripts) — a table of _package.json_ scripts with descriptions.
+
+### Other Tools
+
+* [projectz](https://github.com/bevry/projectz) — generates everything using data from _package.json_.
+* [Mrm](https://github.com/sapegin/mrm) — generates basic README and updates README as part of other task. 
 
 ## Testing Examples
 
 TODO
 
 ## Conclusion
 
-TODO
+README is one of the most essential parts of your projects. Potential users should find answers to all questions they may have when they are evaluating your package, and existing users should quickly find necessary documentation.