Create close-reading recommendation/action report

[jessicaschilling]

This issue is part of Epic 3C: Content-focused "close reading" audit.

Create a report on the close-reading audit effort, including ...

• Summary of analysis
• Detailed analysis
• Specific recommendations on next steps
• Capture these recommendations in GitHub issues for actionable next steps

[johnnymatthews]

IPFS Documentation Report

The step from old docs to new docs has been a vast improvement. A bunch of work has gone into create a better way of serving documentation to users. But there's still a lot of holes that need filling. This report is an informal review of the current state of documentation across IPFS. I'll discuss the following areas:

• Content Guidelines: a general structure for creating new content for IPFS.
• Persona: without strictly defining a persona, discuss what we can get out of creating a definition.
• Learn stuff: suggest different ways in which users can learn stuff.
• APIs: what's wrong with them, where they need to go, and what we need to do to get there.
• Developer relations: how having a solid DevRel strategy can vastly improve the docs.
• Localization: what we need to do and when we need to do it.
• What to do next: what our first steps should be from this point on.

Content Guidelines

The current structure of docs content is heavily based around what has already been written. Articles have been placed into groups that make sense from a content perspective, but they completely lack any sense of hierarchical structure. The initial purpose of documentation is to teach users how to use a particular product or service. The current docs do that, to an extent. The second purpose of documentation is to make it easy for users to learn that stuff. Technically, with enough time and effort, a user could look at the IPFS codebase and figure out how to do everything. But for obvious reasons, that's stupid.

I propose that we move towards building the following structure within the IPFS docs:

Home
├────── Getting Started
 Quick-win is the name of the game here. We want the reader to be able to go through this section in less than an hour and come out the other end with a solid idea of what IPFS is, how to use it, and why it's important.
├────── Developer Concepts
 Explain difficult or new things that IPFS addresses. This could be things like how it's different than a regular database, or how Filecoin integrates into IPFS.
├────── Community
 Guides, links, and references to documentation, tools, and services create and maintained by the IPFS community. There should also be support links in here that are directed to places like StackOverflow and the IPFS forum.
├────── Guides
 End to end tutorials that walk a user through achieving a particular goal. That can be as simple as setting up a node, uploading a single file, uploading a whole site, or changing a website's name server so that it points to IPFS.
├────── Tools
 Things you can use to interact with IPFS. These things might not necessarily be 100% useful or necessary all the time, but they're available all the same.
└────── APIs
 IPFS has a bunch of different APIs available to developers for various different implementations. Each API needs a getting started guide, API references, and an examples section.

Let's go into this map a little bit more:

Guides

This section contains guides on how to do a specific thing from end-to-end. "How to create a single page site and host it on IPFS" would live here. This is the place for long-form guides that tell the user how to reach the desired end-goal. Generally speaking, these guides will take the user at least 10 minutes to complete. They'll cover a bunch of minor elements that get discussed elsewhere in the docs. The point of these guides is to teach users processes and workflows of IPFS. The driving goal of these guides is to teach a user something without them having to jump all over the place to get the information they need. If the want to find out more about a certain process or function, then, by all means, we can link to that function or whatever. But everything necessary to complete the goal of a particular guide should be contained within that guide. This will mean repeating things like installation steps across guides.

Tools

This section is generally for things that you have to install. So the IPFS Desktop and daemon would go here. Since the CLI isn't actually and API then it would go here, since the API section is specifically for APIs only. Users might not have to use all or any of these tools, and the vast majority of them are likely going to be optional. Stuff like installation guides and how-to-do-this steps are going to be here. The Guides section will contain some of the steps mentioned here. For example, installing the IPFS Daemon will likely be repeated in several tutorials, but the content will be the same as what is listed here.

APIs

This is the easiest section to define. If the user is going to programmatically interact with a thing, and that thing has a bunch of available functions and endpoints, then that thing is an API and it's documentation lives here. None of the links listed in the sidebar here will be external links. If the JS IPFS documentation is listed on GitHub somewhere, then the docs will take that documentation and serve it from the docs site. This doesn't mean we're duplicating effort, it just means we're cloning specific folders in certain repositories to gather their API docs. An alternative method would be to house all the API docs within the ipfs/docs repo. However, this might cause the API developers to forget out writing and maintain docs.

Getting Started

This is the most crucial part of the website for new developers or those new to IPFS. Here we'll have a simple tutorial that the user can follow through and reach an ah-ha moment within about 10 minutes. In an ideal world, this tutorial will be kept entirely within the browser session so that the user can learn a bunch of stuff without having to install anything. There should also be some general explanations of IPFS and it's concepts in here. This section is for beginners, so the language and assumptions should reflect that. Towards the end of this section could be some further guided projects users could jump into if they wanted.

Developer Concepts

While this is called developer concepts the articles listed here don't have to relate directly to development. There should be little to no code in this section at all. The articles listed here should go over ideas and the thought processes behind IPFS, essentially the login you need to understand to get the most out of building on IPFS. Things like the decentalized web and storage permanence should be found here.

Community

Pages like Contribution Guidelines and Social Links go here. Not a huge amount of content, but where users should end up if they're looking for help or want to get involved with IPFS a bit more.

Persona

Creating documentation with character can seem a bit strange, depending on the background that you're coming from. The vast majority of corporate documentation is boring and bland by design, it's not attempting to tell a story or convey any sense of theme. Instead, most documentation from large companies strictly tells a user how to get from A to B without explaining why.

This isn't the direction PL should take with its documentation. Documentation at its core is a support function. It's intended as a way for users to teach themselves about a product or service. The fewer people use our docs, the more they'll use other support channels like forums, chat rooms, and mailing lists, all of which take much more effort to maintain and moderate. And for users to want to use documentation, it's got to be fun to use. This is where the idea of a persona comes in.

Writing

Protocol Labs has multiple tones and characters in all of its documentation and marketing materials. That's what happens when you have multiple people all over the world writing content for one company. What we need to do is decide which specific character we want the IPFS docs to reflect. I have a feeling this is going to be an informal, chatty tone with an effort to keep the content easy and fun to read.

Code

Having a code-persona is just as important as defining a persona for written content. A code-persona defines what examples to produce, how they're described to the user, and what kind of projects we give the user. One major aspect of this is to create one major project that we can pull examples from to explain different parts of the IPFS protocol.

We could create a base example project about a car sales service. Throughout all the example and code blocks, we can refer back to this base example project. If we were teaching the reader how to get the hash of a file and store it on IPFS, we could use images of cars currently in-stock in the car sales service.

Having a base example project to work from not only keeps all the articles and sections consistent, but it reduces the need for readers to understand a new project every time they move to a different topic or section. Within a few pages the user should understand what the base example project is, how it works, and ways it can be extended.

The car sales service example I've used in this report is just used to illustrate what a project like this would be for. Suggestions for a more relevant base example project are highly sought-after and more than welcome.

Learn Stuff

The number one search engine in the world is Google. The number two search engine in the world is YouTube. This means if we want to expand our reach to as many people as possible, we need to make more videos to supplement our written content. Right now the docs are pretty much just a wall of text, with a few images thrown in here and there. What we need to have is something like the Laravel Docs. They have their standard documentation, which is great. But they also have Laracasts, a bunch of video courses that explore the topics discussed in the documentation, and show the user how to do stuff.

APIs

There are three major issues with the API docs right now:

1. They're not all in the same place.
2. They're hard to navigate.
3. They're not auto-generated.

To fix these issues we need to do a few things. First off, we need to pull in all the API docs from the three main API repositories that we have: core-api, http, and the cli.

Next, we should create a completely new site view for documentation. Having a long list of functions and endpoints is terrible UX. Being able to preview posts and responses from an API within the browser is incredibly useful, and helps users pinpoint exactly what they need. We'll also need to create useful API examples to complement the API reference listings.

Lastly, we need to work with the Go and JS development teams to help them add documentation-automation into their projects. It might take a bit of work, but it'll be super worth it in the long run.

Developer Relations

WE NEED TO TALK TO DEVELOPERS! This is incredibly key, and I'm surprised that PL doesn't have a significant DevRel team already. We need external developers and users to look at our docs, and tell us why the suck. We can only get so far on dog-food. If we set up a DevRel strategy then the output from those talks, meetings, and conference will feedback into the requirements for documentation and tutorials. Dealing with end-users face-to-face is by far the best way to learn what's required from us, but creating a significant online presence is also handy.

Localization

Having content written in local languages around the world is more of an SEO stunt than anything. Due to utilities like Google's Language processor, when it comes to localizing content for a specific region, it's often easier for the user to choose their own translation software.

However, if there were specific requests from the community to include a localization effort into the IFPS docs roadmap then it should be considered. Something to take into account however is the significant increase in workload when directly translating documentation manually, instead of relying on services like Google or Localize.js. Whenever each document is updated, it must be translated again to make sure everything still makes sense.

What to do Next

Here are some actionable steps that have come from this report:

1. Implement the more structured hierarchy.
2. Design and create video content to reflect written content.
3. Create detailed and interesting diagrams to supplement the written content.
4. Define and document a persona for IPFS docs.
5. Define, develop, and document a code persona for IPFS docs.
6. Automate API and CLI documentation.
7. Discuss a localization strategy.

I'll create issues for these where they don't exist, and then link everything here.

[jessicaschilling]

Video walkthrough from @johnnymatthews is here: https://www.loom.com/share/fc17d21502c14fdc8422a62258627a5a

[jessicaschilling]

@johnnymatthews -- this is awesome, thank you! Can you please prioritize creating the issues you mention above (ideally this week if you're able), so we can wrap up this stage of this effort? Thank you!

[jessicaschilling]

For future reference, the following issues were created as follow-up from this effort:

• Implement the more structured hierarchy. #389
• Design and create video content to reflect written content. Design and create video content to reflect written content. #390
• Create detailed and interesting diagrams to supplement the written content. Create detailed and interesting diagrams to supplement the written content. #391
• Define and document a persona for IPFS docs. #392
• Automate API and CLI documentation. #393
• Discuss a localization strategy. #394

I'll go through these issues to groom in a little more depth, label them accordingly, and link to existing related issues. We'll prioritize them within our Q1 2020 OKRs when we get those pinned down, but for now, OK to call this parent issue closed.