Skip to content
This repository was archived by the owner on Jun 2, 2020. It is now read-only.

Improve README and repo onboarding #114

Merged
merged 6 commits into from
Aug 28, 2018
Merged

Improve README and repo onboarding #114

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5884924
Add information about concept docs to README
Mr0grog Aug 24, 2018
fa5f787
Update styleguide link (the document was moved)
Mr0grog Aug 24, 2018
a246497
Fix typo in README
Mr0grog Aug 24, 2018
92276ef
Fix docs site link and add roadmap/research links
Mr0grog Aug 24, 2018
14e5962
Make readme contributing section a call to action
Mr0grog Aug 24, 2018
403b131
Remove Hugo install from build instructions
Mr0grog Aug 24, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 31 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

This repo is used to:

1. Organize documentation work across the IPFS project
2. Host a documentation website for IPFS meant to replace what is currently at https://ipfs.io/docs
1. Organize documentation work across the IPFS project.
2. Host the documentation website for IPFS. It gets published to https://docs.ipfs.io/.

Read the Captain's Log or check the [issues](https://github.com/ipfs/docs/issues) for updates: [ipfs/docs#47](https://github.com/ipfs/docs/issues/47)

Expand All @@ -20,42 +20,61 @@ IPFS documentation currently has several acute problems:

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

Check the near-term roadmap for this work in [issue #58](https://github.com/ipfs/docs/issues/58).

*Read a more detailed summary of our research on documentation problems in [issue #52](https://github.com/ipfs/docs/issues/52) or at [/ipfs/QmNj68gTzAs9QbfMKzMGurXP2WCmA6GTcKuUkWm4kBV1Qn/html](https://ipfs.io/ipfs/QmNj68gTzAs9QbfMKzMGurXP2WCmA6GTcKuUkWm4kBV1Qn/html/).*


## Contributing content

The documentation site contains several different kinds of content:
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. Please also take a look at [#60](https://github.com/ipfs/docs/issues/60) for planning and ongoing work in this area.

2. **Guides, examples, and tutorials.** Most examples currently live in other repos, like [js-ipfs examples](https://github.com/ipfs/js-ipfs/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.

3. **Reference Documentation.** Please see the issues in this repo for current activity around reference/API documentation.
3. **Concept guides.** These are a special category in the *guides* section listed above. Concept guides are intended to present a brief overview IPFS-related concepts that might be new to people. They live in the `content/guides/concepts` folder and should strive to answer:

1. **What** is this?
2. How does it **relate** to the rest of IPFS?
3. How can (or should?) you **use** it? (Note: sometimes the answer is that you should understand it, but *not* use it. *Bitswap* is probably a good example.)
4. **Where** do you go to learn more?
5. What is the **current state** of affairs?

See a list of concepts we need help with by [checking the issues](https://github.com/ipfs/docs/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3Acontent+concept) or reading through [issue #56](https://github.com/ipfs/docs/issues/56)

4. **Reference Documentation.** Please see the issues in this repo for current activity around reference/API documentation.

5. **Community.** If there are important missing community links, file an issue or PR here!

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 [the issues](https://github.com/ipfs/docs/issues). If you decide to work on one, please post to the issue to let us know!

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/ipfs/community/blob/master/contributing.md).

4. **Community.** If there are important missing community links, file an issue or PR here!
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).

Before posting a PR with documentation changes, please also check [our styleguide](https://github.com/ipfs/community/blob/master/docs-styleguide.md).
[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/contributing.md)


## Developing the site
## Building the Docs Site

### One-Time Setup

1. [Install Hugo](https://gohugo.io/)
2. Install [AEgir](https://www.npmjs.com/package/aegir)
1. Install [AEgir](https://www.npmjs.com/package/aegir)

```sh
npm install -g aegir
```

3. Download IPFS libraries and tools (e.g. go-ipfs, js-ipfs) and generate their documentation:
2. Download dependencies and IPFS libraries (e.g. go-ipfs, js-ipfs) and generate their documentation:

```sh
make install
```

This installs dependencies and generates source files from other projects (e.g. API documentation; theme resources from the `ipfs-css`, etc).

When dependencies or external packages (like `go-ipfs`) have new releases, regenerate files based on them by running `make resources`.
When dependencies or external packages (like `go-ipfs`) have new releases, you should regenerate files based on them by running `make resources`.


### Build and Run the Site
Expand All @@ -78,6 +97,6 @@ We believe in hosting IPFS’s documentation on IPFS, and that’s much easier w

All software code is copyright (c) Protocol Labs, Inc. under the **MIT license**.

Other written documentation and content (c) Protocol Labs, Inc. under the [**Creative Commons Attribution-Share-Alike License**](https://creativecommons.org/licenses/by/4.0/).
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/).

See [LICENSE file](./LICENSE) for details.