Documentation Structure

1

Intro:

At the Contributors Call (6/18/20) today, it was decided that I (LB) will be the Documentation Lead as many of the Cultivation related initiatives (like the mind map and the website UX audit) I’m a part of intersect well with the Documentation Branch structure.

Read the below description, or skip straight to the new SourceCred Documentation Index and add to it.



Docs Structure Proposal:

:busts_in_silhouette: The Three Documentation Audiences:

While I was puzzling over our website’s UX and what I wanted from it, I identified three broad audiences that I think are trying to solve their problems by coming to our website (and therefore our Documentation).

People who are:

  • Trying to understand what SourceCred is.
  • Trying to become a SourceCred contributor.
  • Using or hoping to use SourceCred in their community/project.

:spiral_notepad: The Corresponding Documentation Categories and their Sections

Based on these groups, we could create three distinct branches of the documentation organized by audience:

1. :open_book: Learn More About SourceCred

  • The vision / strategy / values / philosophy.
  • The mechanics / core functions / practical application.

2. :wrench: Help Create SourceCred

  • Social norms of the community
  • Getting involved

3. :play_or_pause_button: Using SourceCred in Your Community

  • Set up guides
  • Technical Documentation
  • Community building guidance

I put some example sections within each of the three categories of this proposed documentation structure. Each of those sections will have its own list of Docs, and there’s likely more sections than I’ve shown in my example above.



:mega: The Actionable Stuff:

I’ve begun putting together a spreadsheet for those who are working on writing Documentation to organize themselves. If you’re involved in docs or have a good perspective on the project (whether because you have a lot of context, or because you’re a newcomer) please please add your docs to this new index!

Please:

  • Add the docs you’re writing currently to the spreadsheet.
  • Comment on the structure of the Sections, Categories, and Fields in the comments of this Discourse Post.
  • Add docs you’d like to see written (mark their status as “wishlist”)

Check it out now: SourceCred Documentation Index





Thanks!

<3 LB

2 Likes
2

Really like the high-level structure, makes a lot of sense.

Super busy with other things right now, but looking to pick off a doc or three when I get the chance, and happy to support doc efforts generally in any way I can.

3

Lovely! Probably the biggest task in my mind right now is taking stock of everything that’s in the process of being written, and everything that’s on the wishlist. Adding things to the documentation index spreadsheet would rad af.

1 Like
4

Hey @LB and @s_ben

I was looking over the documentation task list and then thinking about the real audicences.

Off the top of my head the classes of people are as follows:

  1. A person who just landed here wanting to learn more about SourceCRED as a user that is in a system testing out SourceCRED where they contribute or lurk. There are two different kinds of people in this group. a) People just learning how they might optimize their sourceCRED rewards on the other sites they are encountering this on. b) People who are interested in helping here.

  2. Another person is someone who really wants to understand the technical details of sourceCRED because they want to install and use it within another community.

  3. People who just heard about sourceCRED and are looking for a quick introduction document about sourceCRED from an authoritative source.

I saw this at Maker and in other places where there is no real good ELI5 or ELI15 15minute quick introduction guide to the basics of a complicated system. Something that is a quick read, easy to understand bulleted points that convey important key points to remember that should have links to more in depth details on that specific point.

The above often is a good start at organizing what often times is a very complicated project into some simple easy to digest concepts for people. The document itself can serve as a top level introduction document that can also link to a medium level primer (take maybe 1-2hrs to digest everything) which then branches off into the advanced documentation on every mid-level topic.

The idea of breaking sections into ‘beginner, advanced user, expert user’ is often quite useful as the documents come into being they can be organized and re-organized to have a structure that flows easily.

Say for example in the beginner document we have something simple like sourceCRED allows communities of users to self-organize rewards for contributions based on community defined values. rewards would be a link to grain/CRED, community defined values would link to more information on a simple explanation of the sourceCRED algorithm etc. The beginner document taking people to more beginner explanations until they drill down or choose advanced, then the advanced giving them links into the advanced docs until they bubble up to the beginner again, or descend down into the expert…

I keep thinking information about sourceCRED needs to be compartmentalized into three key aspects.

  1. Users that don’t care about implementation but just are trying to understand how to optimize their rewards in the system they are immersed in that may or may not want to contribute here.

  2. Experts or people looking to implement the system, get a license, etc.

  3. People who specifically want to help work in the sourceCRED initiative itself.

Each of these three people will want and need very different resources imo. I think producing documentation that caters to the different needs will be quite useful for the entire community.

I also think about Introduction topics, advanced topics, and support topics for each of these groups.

I have a lot on my plate lately but I may just try to write up a very simple introduction to sourceCRED for group (1) and post it somewhere. I am so not a github kinda guy so If I can just post it in the forums for discussion that would be of immense help to me. Someday I will deal with github. I wonder what does a community like this do when someone wants to help but for varying reasons can’t or won’t work within a particular model (like github). Is there a way to accomodate such folks to make contributing less technically cumbersome for them or does this lead to other issues?

EDIT ADD: I wanted to say I have been scanning the sourceCRED.io website and see this is a place where some re-org might be fruitful. Definitely a good place to put some work into. As I poke around I may just take all of the pages and make some notes on what I am finding everywhere to see if I can throw a stab at ‘introduction’ documents and perhaps some ‘advanced’ ones. Mostly as a side project to whatever is going on now. This way we can kind of parallel some work and see what looks better to the community. I always like getting choices if I can, but I hate idea 1/2 or 1/3 of the work might be tossed. Really hard to do something right the first time…

Anyway just some thoughts on this subject. I will see if during some spare time I can flesh out something to present documentation wise. I thought about doing this for Maker but the prospect was daunting from a complexity standpoint. sourceCRED seems simpler when I look at what is up now.

1 Like