Code persona

Docs can be confusing, especially for increasingly complex topics like IPFS. There are lots of moving parts, and it's easy to get confused. Example use-cases and code-blocks often serve to make things easier to understand and allows for a more hands-on experience. However, examples that come from different use-cases and projects make it harder for the reader to understand the topic. The solution is to create a theme for all samples to be based off.

Having a single theme keeps code examples self-contained and consistent. It doesn't make the problems any less complicated or less technical, but it makes the reader need to think less. The reader doesn't have to spend time continually re-visualizing the larger project at hand if the main project is something they're already familiar with.

The theme

The interplanetary part of InterPlanetary File System comes with obvious space connotations, so it makes sense that example use-cases and code examples are based around the final frontier. With this in mind, when creating code-examples to illustrate your ideas, try to keep them within this space theme.

We can expect the vast majority of IPFS users to be familiar with the planets within our solar system and some of the more famous telescopes, satellites, and space rocket names. However, it would help if you tried to stay away from more exotic or niche planetary bodies. Not everybody is going to be familiar with the Andromeda Galaxy, and it may confuse some readers. Also, keep in mind that many language translators will be able to deal with common planet names like Jupiter or Mars but may struggle with less common names.