frijol / docs-2 Goto Github PK

Mondays at 15:00-15:30 UTC / 4:00-4:30 pm BST / 7:00-7:30 am PST

📞 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:

1. To organize overall documentation work across the IPFS project, as managed by the IPFS Documentation and Developer UX Working Group ("Docs WG")
2. 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!

• @cwaring
• @ericronne
• @dominguesgm
• @jessicaschilling
• @terichadbourne

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
1B. Define deprecation plan from old to new (non-beta) docs platform
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
2B. Augment “is this helpful” feedback mechanism in docs beta to get more actionable info from users at point of feedback
2C. Conduct mid-stream usability testing of docs beta platform and revise beta deployment plans as necessary
2D. Conduct quantitative voting-based testing to confirm direction of docs beta, and revise deployment plans as necessary
2E. Define documentation’s and ProtoSchool’s place within the entire IPFS information ecosystem and draft a design-thinking-based strategy for future work ("content meta-audit")
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
3B. Close high-value existing missing-content or inadequate-content issues
3C. Conduct a content-focused “close reading” audit of existing IPFS docs to identify and prioritize work on weak or incomplete docs
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
4B. Create or improve ProtoSchool tutorials using content adapted from IPFS Camp
4C. Create or improve docs pages/entries using content adapted from IPFS Camp

• Prioritized features list for next-gen docs platform to be implemented beginning in Q4
• IPFS user/goal personae illustrating the goals, motivations and potential frustrations of key current/potential IPFS users
• Research/test plan and summaries for Q3 2019 OKR research efforts
• Documentation platform evaluation elaborating upon our decision to build docs beta on VuePress

We're undergoing major renovation to our docs in Q4 2019, but we would still love ❤️ your help to improve existing items or make new ones even better! Here are some ideas to get you started:

1. Join us on our weekly call! See the top of this readme for full details on how and when.

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

3. 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 Improvement label 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.

4. Help us improve how we present reference and API documentation. As part of our beta docs platform launch, 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.

1. Install AEgir

   npm install -g aegir

2. 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 running make 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.