Mondays at 16:00-16:30 UTC / 4:00-4:30 pm GMT / 8:00-8:30 am PT
NOTE: No meetings on 23 or 30 December 2019. See you in the new year!
📞 Zoom: https://protocol.zoom.us/j/614386160
📙 Notes from current and past calls can be found here.
🎬 Video recordings of past calls can be found in our YouTube playlist.
This repo is used for two purposes:
- To organize overall documentation work across the IPFS project, as managed by the IPFS Documentation and Developer UX Working Group ("Docs WG")
- To host the documentation website for IPFS, available at https://docs.ipfs.io/
After a busy and productive Q3 2019, the Docs WG is looking forward to putting into action a lot of the research and strategic work we accumulated over the summer and early autumn — as well as continue apace with more immediate/tactical improvements to the existing IPFS docs landscape. Our goals for Q4 2019 are below, and you'll notice that they include (among other things) execution and support work for one major development: launching a new beta docs platform to eventually replace docs.ipfs.io. In parallel, we're also queuing up improvements to a variety of documentation items — and types of items.
Want to be a beta tester for the new docs platform? We'd love to have you take part. Let us know!
You can also view our progress against these in the IPFS-wide OKR (Objectives and Key Results) tracking document, or filter this repo's issues for ones with labels containing OKR.
| OBJECTIVES & KEY RESULTS | RANK | MID-Q | PROJECTED | FINAL |
|---|---|---|---|---|
| 1 - Launch beta docs platform in order to offer users an improved venue for learning | ||||
| 1A. Launch beta of new docs.ipfs.io platform; content initially at parity with existing site, but with next-gen information architecture (work complete, live launch tentatively 10 Jan) |  |
0.5 | 0.9 | 1 |
| 1B. Define deprecation plan from old to new (non-beta) docs platform |  |
0.2 | 1 | 1 |
| 2 - Improve our understanding of user needs and map out improvements accordingly | ||||
| 2A. Define metrics collection for docs beta site in order to effectively define KPI-based success of docs beta site | |
0 | 0.9 | 1 |
| 2B. Augment “is this helpful” feedback mechanism in docs beta to get more actionable info from users at point of feedback | |
0.5 | 0.9 | |
| 2C. Conduct mid-stream usability testing of docs beta platform and revise beta deployment plans as necessary | |
0.5 | 1 | 1 |
| 2D. Conduct quantitative voting-based testing to confirm direction of docs beta, and revise deployment plans as necessary | |
0.5 | 0.9 | 1 |
|
||||
| 3 - Improve docs content based on metrics, research, and community input | ||||
| 3A. Identify and fix specific docs pages/items based on user feedback mechanism or other metrics | |
0.5 | 1 | 1 |
| 3B. Close high-value existing missing-content or inadequate-content issues | |
0.5 | 1 | 1 |
| 3C. Conduct a content-focused “close reading” audit of existing IPFS docs to identify and prioritize work on weak or incomplete docs |  |
0.2 | 1 | 1 |
| 4 - Enhance ProtoSchool and docs.ipfs.io content using IPFS Camp content | ||||
| 4A. Complete review of IPFS Camp content identifying how it can be applied to create new ProtoSchool tutorials, enhance existing ones, or improve the docs.ipfs.io site | |
0.2 | 1 | 1 |
| 4B. Create or improve ProtoSchool tutorials using content adapted from IPFS Camp | |
0 | 1 | 1 |
|
- Prioritized features list for next-gen docs platform to be implemented beginning in Q4
- Vote on your priorities for the next-gen docs platform!
- Docs beta repo — WIP in rapid evolution
- IPFS user/goal personae illustrating the goals, motivations and potential frustrations of key current/potential IPFS users
- Research/test plans and summaries for Q4 2019 OKR research efforts
- Research/test plans and summaries for Q3 2019 OKR research efforts
- Documentation platform evaluation elaborating upon our decision to build docs beta on VuePress
We would love ❤️ your help to improve existing items or make new ones even better! Here are some ideas to get you started:
-
Join us on our weekly call! See the top of this readme for full details on how and when.
-
Claim an issue labeled "help wanted" in either this docs repo or the IPFS website repo! All our issues are T-shirt sized and roughly difficulty-graded (both using labels), so have a look for something that interests you in the time you have available, and dive on in! Leave your thoughts and questions in issue comments, and we'll get back to you as soon as possible.
-
Create (or improve) an example, tutorial or concept guide! At present, we have a variety of how-tos and concept guides either living in this docs repo, or linked to from the nav menu at docs.ipfs.io. However, every new item we can offer makes it easier for the world's community to use and build on IPFS. If you'd like to write a new example/tutorial or concept guide, take a look in our open issues for items with the
OKR: Content Improvementlabel and see if any already-identified needs appeal to you. If you'd like to write something entirely new, feel free — PRs are welcome! Or, if you'd just like to improve existing docs content, feel free to fork it and add your suggestions. -
Help us improve how we present reference and API documentation. In Q1 2020, we're investigating the best way to improve how we present reference materials like API documentation and command-line dictionaries. Got thoughts? Please discuss them!
If you're able to contribute to any of the categories above, we thank you in advance -- your work directly improves the future of IPFS for the global community! Before posting a PR with your changes, please be sure to check our documentation style guide and the overall IPFS contributor guidelines so we can ensure that docs are clear, consistent, and simple to read. Finally, please make sure to follow the IPFS code of conduct.
-
Install AEgir
npm install -g aegir
-
Download dependencies and IPFS libraries (e.g. go-ipfs, js-ipfs) and generate their documentation:
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, you should regenerate files based on them by runningmake resources.
- In the root directory, run
make dev - Load http://localhost:1313 in your web browser
- Edit and add things!
To create a production build, run make build instead. You’ll find the final static site in the public directory.
All software code is copyright (c) Protocol Labs, Inc. under the MIT license. Other written documentation and content is copyright (c) Protocol Labs, Inc. under the Creative Commons Attribution-Share-Alike License. See LICENSE file for details.