I’d like to introduce The Explainers Initiative.
It’s something I’ve been working towards with my drafts and which I want to showcase as Status following its principles of openness from the technical writing side.
The Explainers is an open repo of content that’ll end up on https://our.status.im as tutorials, guides and explanatory posts about Serenity (Ethereum 2.0) (for now) but which relies on peer review in an effort to crowdsource knowledge and explanations before they have to be corrected. It will also serve as a backup database of sorts so that if we ever decide to move away from Ghost, it’ll be extremely easy to port at least this stuff.
I wanted to make this available sooner, but rabbit holes drew me in and I’ve joined several communities which have a lot to say about all this Serenity stuff.
Why do this?
For one, it’s openness - showing the world our drafts announces our intention to cover a topic and encourages others to contribute, but also shares our workflow with others and allows them to voice their concerns and opinions before publication time, as that’s when inertia has already set in and it’s harder to discuss changes.
The repo aspect also helps with corrections and suggestions - people can comment on individual lines in the repo right there from the UI, and for bigger changes they can send in PRs which can also be discussed line by line.
Additionally, by following a pre-set structure for file and folder layout, we can easily use a command line script to auto-import the files into any third party solution at any point in time, or even into a Status extension which will know where to find stuff (e.g. /status what is nimbus? or /status what's new in Serenity?). All published posts get a meta file which lists their locations online for each locale that exists, so it’s easy to find them. Example meta file.
Localization
The process also lends itself nicely to localized versions of the posts - something I think we should definitely work on. For example, I live in Croatia which is a 2.5th world country where people’s knowledge of English is… iffy. I also often speak at various ex-Yugoslavian / Balkan conferences and the common complaint is that these locales simply have nowhere to learn from. Sure, there’s the odd translation of an Antonopoulos book but by and large they’re left to their own devices and StackOverflow browsing. This is why I started Bitfalls last year (bilingual blockchain tuts) and why I’d like to see more localization happen here.
I’m fully aware that it’s not technically trivial to implement multi-language into https://our.status.im, nor would it be smart since we cannot guarantee the presence of translated content for every language of every post, so the idea is actually to offer a place where a localized version can be saved and improved with PRs, and then link to the published version in the aforementioned meta file. That way we have a directory of all our posts and their non-English counterparts across the web, which helps us keep track of content, but also helps us recognize translators, active members of various non-English communities, and provides a wide range of other benefits, mainly in terms of growing the ecosystem.
The first two posts - Nimbus and Validators - have been translated into Croatian. Nimbus has been published, too - here and the source is here. The English version there leads back to Our.Status while the Croatian is accessible there. We should encourage local web portals of different countries / languages to do the same whenever they ask permission to do so.
Endgame
The end goal is to have a pool of active contributors that collaborate on new public content, and to turn the repo into an educational hub for the community by the community. Ultimately, we’d have some kind of NFT kudos system for the best contributors and other incentives, but that’s a long ways off and only if it catches on.
Instructions if you’d like to join as a peer or author can be found in the repo’s README. If there are any questions, shoot. I should say that this is just an experiment, and if it doesn’t pick up steam I’ll just move the repo and use it for drafts regardless, because I think it’s a really handy way of asking for feedback in final stages of article outlines.