Create Library of RChain

[pmoorman]

Overview

We're working on a decidedly decentralised effort to craft a tech docs library to help developers and DApp decisionmakers find the information they need to confidently commit to our platform.

This initiative has evolved from discussions with @PatrickM727 and @ottermagically about an RChain library. The rough idea is that if someone discovers RChain and would like to do a "deep dive" to learn more about it, they should have a reputable source to get that info.

The platform should have the amount and depth of content that makes someone say "yeah, I feel comfortable to commit to building on this platform!"

Live work-in-progress: https://rchain-docs.netlify.com/

We have a RChain :: unified documentation Google Doc where we track work

SMART objectives

A library like this will be an ongoing effort. The best measure of completion I can come up with is...

"All the pages that currently exist in the navbar / sidebar of the work-in-progress website are fleshed out and authoritative enough to be publicly available"

Note: Joshy only wants to sponsor content creation under the DevEd label, and thus anything related to building the website and other such things shouldn't be considered to be part of the scope.

Tentative budget breakdown:

• Revamp / update of the architecture document (ArchDoc): $3000
• Features pages: $2000
• Rholang documentation: $TBD (I'm not sure how much is available at the moment)
• Getting started pages: $1500
• Governance pages: Sponsor needed
• Economics pages: Sponsor needed
• Technical documentation: TBD

I know that this is merely a "best guess", so further suggestions are welcome.

Timeline: I'm aiming to go live mid-November at the latest (~4 weeks)

Sponsorship

The DevEd label can provide sponsorship for writing content focused on onboarding and getting developers. In particular, we could use help with the following:

1. Surfacing the most interesting and relevant pieces of content from JIRA/Confluence and developer.rchain.coop, and making it available in an easy-to-read format. (e.g. info on "how does sharding work?" and "how do namespaces relate to each other?" and stuff like that)

2. Writing documentation for Rholang

3. Writing documentation about validator economics, running nodes, etc.

4. "Getting started" information, to help people quickly find the resources they need to take a next step.

5. Help @dckc and @JoshOrndorff to improve the ArchDoc section RChain Architecture document revision #580

I imagine we'll have to synchronize with @JoshOrndorff about the details & sponsorship amounts once you are ready to commit to a certain scope of work. Both Joshy and Patrick have expressed written support for this project already.

How to get started

Let me know here what content you'd like to work on. For edit access, reach me here or on Discord (@pmoorman). You can also contribute by compiling information for a relevant page, and providing it here in markdown format (and I'll integrate it in the site).

[dckc]

jonathanks = @ottermagically

[dckc]

Why doesn't this follow the ISSUE_TEMPLATE task form?

[pmoorman]

know what's weird, I can never actually tag @ottermagically. I don't know why it doesn't work, but it doesn't. Only person I'm aware of that doesn't work, everyone else is fine!

Why doesn't this follow the ISSUE_TEMPLATE task form?

I thought it was more "guideline" rather than a requirement. I try to strip out anything that I deem non-essential. Are there any parts I should add back in?

[pmoorman]

@JoshOrndorff if you could jump in here and "officially" say "this looks good to me", that would be awesome 💯 👍

[dckc]

I thought it was more "guideline" rather than a requirement.

If you just want to chit-chat, then we can add the Discussion label. But if you're seeking a bounty reward, it needs the SMART stuff:

• Estimated Budget of Task:
• Estimated Timeline Required to Complete the Task
• How will we measure completion?

[pmoorman]

damn, you're right. Oke, updated to reflect that.

[pmoorman]

If you all don't mind, I'll keep track of regular progress here. Even if not not everything is funded, but I'd like to work in the open, anyway.

Yesterday

1. Added a scaffold for a team page (@TrenchFloat maybe you feel like sorting out the content, based on this template?)

2. Added a page for conferences & meetups (same here, the content needs some more work)

3. Fixed styling, so we have cool "tips" boxes now, in RChain-branded colors (see conference page). Also added a favicon.

Today

4. Added basic content to the research page

Also spoke with other stakeholders about how this piece of work can relate to their efforts (@PatrickM727 for marketing, @ian-bloom @barneycinnamon and Karen for governance, @derekberes and @ottermagically for not anything in particular, and Ned from RChain Solutions)

[azazime]

Is this some kind of a joke or the restructuring was not what we thought... A library??? And for that amount???

[dckc]

I'm not sure what you mean by "the restructuring"; help me out?

p.s. The needs-SMART-objective label is not for objectives that you disagree with; it's for issues lacking an objective altogether.

[pmoorman]

@azazime I don't quite understand your comment. You seem to be sarcastic, but it's hard to pick up where you're going at. Please clarify what your concerns are

[azazime]

Well its not a very terrible idea but I feel there's already so many things that is more like a library but is been under-used like RUB, Divydao, the community forum, Rchain official blog and so on. The idea is not the worst in the world but for that amount I can hardly see the "value for money"

[dckc]

Fair point. We're still brainstorming to some extent. The budget is just something to start a conversation. Evidently it worked :)

…

On Tue, Oct 23, 2018, 12:36 AM Andrew ***@***.***> wrote: Well its not a very terrible idea but I feel there's already so many things that is more like a library but is been under-used like RUB, Divydao, the community forum, Rchain official blog and so on. The idea is not the worst in the world but for that amount I can hardly see the "value for money" — You are receiving this because you were assigned. Reply to this email directly, view it on GitHub <#1004 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAJNykhou8GsWarESYek6mrm3c3Bw6WDks5unqrygaJpZM4XtUAe> .

[pmoorman]

@azazime

I feel there's already so many things that is more like a library but is been under-used like RUB, Divydao, the community forum, Rchain official blog and so on.

Fair point, and I agree. Part of what we're learning is that just building platforms without a distribution / engagement strategy, isn't working. When we commit to building something, we should also commit to marketing it, inside and outside of the community.

Let me use this opportunity to make a start with addressing that concern....

How I'm planning to drive traffic to this platform:

1. I have been talking with close to 20 people about this initiative, including Patrick, Kevin W. and Joshy from marketing, and devs / technical people that can contribute to the archdoc. The feedback has been overwhelmingly positive, and engaging these people early helps drive distribution within the community. I am working actively on bringing more collaborators on board.

2. Patrick has already expressed support to host this on library.rchain.coop. That specific subdomain might still change, but we're aiming to host this as part of the official RChain experience.

3. I am engaged with the main website team, and we will sync it into the experience there. I'm also in touch with Derek Beres who manages the email marketing efforts (amongst other things), and I think we can plug this platform into the onboarding there.

4. Once the platform is live, we would do well to work on a basic backlink / SEO strategy, to make this platform pop up in Google. I have experience doing this, but in all cases it's still lots of dumb and boring work to build a quality backlink profile.

5. On the long run, quality content will reign. If we get the majority of stakeholders to publish their evergreen content here, that'll be a sustainable long-term strategy. We achieve this through open and straight-forward write access, so many people can edit and contribute in parallel, without bottlenecks. I chose the platform architecture to specifically support that as well as possible.

That's a start. If you want to, feel free to think along. If you still feel worried about it (probably, you should be), then help me find the biggest gaps in my thinking, so we can make this a success.

RE: budget

Just to clarify these budgets: Contrary to some of the examples that you mentioned (community forum, unofficial blog), I have developed this platform without incurring any costs to the Coop as of yet. Joshy supports funding for creating new DevEd content. This means that the stated costs are for creating content that can live on this platform, but could as well live on other platforms (for instance: the archdoc would need an update regardless, etc.).

To be fair: I'll still look for sponsorship on developing the platform itself, too. But that's because I believe it'll be valuable, and I'm committed to proving that. So there my personal incentives are aligned with addressing your primary concerns.

Does that help clarify?

What do you think of this distribution approach?

[JoshOrndorff]

Indeed I will support content creation related to educational materials, examples, architecture, etc. I don't know how to do that in a big issue like this without the possibility of an excited bounty hunter coming along and twisting my words into sponsoring the entire thing for an outrageous amount.

Just to make an on-the-record statement, I like what you're doing here and hope it gets worked into the website. That is beyond the scope of what I'm allowed to sponsor though.

@pmoorman Have you had any interaction with Kevin about this? I'd love this bounty to be sully sponsored and be synergistic with the "learning center" that we talk about sometimes or developer.rchain.coop. That would take a ton off of my plate and allow me to focus on creating content and leading learning groups and whatnot. Sounds much nicer than figuring out who to talk to and in what format to get content that has existed since before I started working for the coop into the website.

[dckc]

OK, while we're branstorming on scope, I'll put the flag back on...

[pmoorman]

Few thoughts regarding scope:

1. Maybe it's best to treat this as an "umbrella" issue with, without a budget, and reference other issues that have specific scopes and clear budgets. (e.g. the ArchDoc revamp has it's own budget & issue)
2. Doing this would also allow different pieces of content to be sponsored by different organizations. If Joshy can't sponsor governance content (for instance), maybe other people can. Different issues would support this better, from an accounting point-of-view
3. I believe specifically that content around "RChain in non-technical terms" (accessible for both devs and DApps decision-makers would fit Joshy's scope. I intent the "feature pages" to provide this. This specific bounty I could break out into a separate issue, as per point 1.)
4. As an aside: @PatrickM727 reached out to request if I'd like to be a pm on the website, and this library effort. This is in the early stages, but could provide an alternative way to support the core of this effort. I don't know how it can support others like @TrenchFloat, though

My suggestion —for now, at least— is to swap the SMART label for the Discussion label...

[JoshOrndorff]

1,2. I love the idea of this being a discussion meta issue and other more focused bounties for content.
3. This is a huge synergy with our elearning initiative
4. You should do it. I also don't know how to support @TrenchFloat along with this offer it's confusing. That's why we need things like @glenbraun 's RHours. Luckily we're supporting a POC dapp for it. #1006

[pmoorman]

@JoshOrndorff understood!

For anyone who might read this and also wonders, as I did, "what's this RHours thing?" Here's a link: https://github.com/RHours/RHours

point 3 => yeah, plan to start work on that in the next week or so. Will cross-reference the issues when I create them.
point 4.1 => I'll let everyone know how negotiation goes, in this issue.
point 4.2 => RE: trenchfloat et al. ...still something to figure out. The way I read it, at least Trenchfloat can help create DevEd content (and potentially other content that has sponsors), which seems good enough for now.

[pmoorman]

On a completely unrelated note:

small victory of the day

I got previews to work on Forestry. Now @TrenchFloat can inside Forestry (our CMS-ish thingy) preview his work before publishing, and see how things look before it's committed to git.

It still works rather clunky for my liking, but it's better than not being able to preview (as it was, until now)

Coming up next:

1. Need to spend some time on the governance surrounding this project. Most importantly, that includes making a deal with Patrick, and also making sure we capture somewhere the Wikipedia-style open write access spirit of the project.
2. Then, I'll try map out the technical documentation sections of the website, and see what we can do there to get that started. (@glenbraun be warned, I might ping you on Discord about that!)

[dckc]

I tried out mediawiki today... didn't really come up with anything that I like.

https://info.rhobot.net/wiki/Main_Page

under the hood: https://my.divvydao.net/?#/apps cloudtron

[dckc]

I made some good progress tonight: check out https://rchain-docs.netlify.com/ and hit the big red button to get to https://rchain-docs.netlify.com/platform/roadmap.html

https://github.com/pmoorman/RChain-docs 5a5baa3

[dckc]

I'm working on gRPC docs.

https://rchain.atlassian.net/browse/RHOL-1065