Documentation! Oh my

Hello happy people!

We have improved our documentation process enormously, so it’s time for some people from each team to step up and become the janitor for your area of expertise.

We’ll need one janitor to be responsible for each team - from P2P, core-chat, Nimbus, hardwallet, Dapps and Developers etc etc. Being responsible doesn’t mean you have to write all the documentation, it just means you are the go-to person to ping when more documentation is need, or when it should be updated and then you need to help the technical writer either produce the content or point them to the person who can best do that.

In terms of the design: Hazel is working on it right now. I have re-skinned the site to use in line with the Embark docs, so everyone is suing the same theme, which we can then just style across the board according to the new designs. We will also implement a global header navigation.

There is an edit pencil in the top right of each page, which will take you straight to the relevant file on the develop branch. Feel free to commit directly to develop - it builds to so that you can see immediately the effect of your changes and submit a live link for review, which should make reviewing and staying on top of all this a breeze.

master builds to the gh-pages branch, which is then served to, and is protected, so only changes that are OK’d on develop get merged there and sent off to the live site.

Looking forward to seeing a vibrant documentation site form out of all our individual contributions!

Hey @cryptowanderer,

this sounds like a good initiative! I’ve got a questions on this though:

Is the goal to have documentation of various projects in a single place?

You’ve mentioned that somebody of every team should be available for keeping the docs of the corresponding project up-to-date. But then you mainly referring to “the site” and [dev-] and how changes can be made to that side. Does that mean we want to move documentation from all project to that site? Or do we keep docs for each project separately, just making sure that they all follow the same theme?

Shouldn’t this be the responsibility of the product manager of each project?

Hey @PascalPrecht - no, the goal is not to have documentation of various projects in a single place.

The goal is to have all our docs using the same site generator and the same styles, so that we keep a consistent visual language across all platforms. However, each site will live in its own repo, and be managed by that team. We have chosen to go with in line with the Embark team, so you all won’t need to do anything, yet. Once the designs are finalised, I will help implement them on the Embark site without touching any of the content.

The global navigation header is the same across all sites so that it is easy to get from one place to another, understand the whole project, and see everything we’re doing. However, each “space” is owned by that team. Embark does a pretty good job keeping docs up to date, so that’s all you’ll need to focus on going forward.

What I mention wrt “the site” applies specifically to - other spaces and teams need not have the same build pipeline (even though I think it’s dope :wink:)

1 Like