Skip to content

Scoping out next Level Docs

time-estimate: TBD
name: Scoping out next Level Docs
assignees: @djudjuu

Description

Create an 8Lines version of fathom and a scaffolding for the new documentation. Therefore defining the target audience is crucial:

The target audience of the documentation will be members of an RC-like community: This means potential readers...

  • have a positive attitude towards technology/software, yet possibly no previous knowledge.
  • are members of a community
    • that operates with high-degrees of autonomy and little top-down commands.
    • where people interact without expecting (bigger) economic benefits, but for idealistic, altruistic motives.
    • where members generally trust each other.
  • value self-directed learning/making over being handed things down.

Generally, we want the documentation to be as brief as possible, focus on the benefits of fathom as a 'coordination lubricant' for small scale communites. Also, but not primarily, we want to show that those same mechanism can naturally scale to a much bigger (global) level.

For brevity we want to keep things as general as possible, but also use this process to sketch out an appendix, where we want to eventually provide reference implementations/concrete examples/specifics about the all details of the protocol (e.g. formulas for payout distributions, incentive structure), so that it becomes clear that fathom-mechanisms are not limited to high-trust small scale communities.

Motivation

The old documentation is too techy, partly outdated and application and scale specific. References: Check out the detailed analysis of the the documentation and these notes from @jaredpereira 's and @djudjuu state-of-the-fathom-docs-call from the 20.5:

  • takeaways
    • agreed on economics as vital, yet finding new wording could be helpful
    • governance aspect needs to be stressed and moved up (concept governance aka network/fathom instances governance)
      • ????: Do we want multiple fathom instances in the beginning?
    • NEW ISSUE: allow more than one clone as parent
    • no point interlinking documentations for RClike communities & crypto incentives (steal, challenge period, etc...)
    • appendices can be big, there are not brwosed through
    • simulations would be cool, yet what for?
    • code: documentation in comments, top of file, top of function, no parameter-comments, inline only where necessary
  • MOVING FORWARD:
    • create an outline (scaffolding structure) of the doc as it should be for small scale communities
    • write appendices only in pseudocode
    • estimate time then

Timeline

TBD

Deliverables

1. 8 Lines:

This is a highly condensed summary of fathom's core idea. It is targeted to experts who familiar with the subject, so knowledge of the field and related work is assumed. The focus needs to be on the contribution that is new and why it works. Formulating this will help us being clear about what is the main point we want to get across in the documentation at large.

2. Scaffolding

A scaffolding is high-level documents that combines the core arguments from the 8Lines ,the background information necessary for non-experts and the didactics of a document. It is structured in the sections of the text, but instead of actually making the arguments, the scaffold is written a meta-level, explaining what the text that will ultimately be part of the section must accomplish and why.

It should allow us to make an informed time estimate on how long it will take to write those sections, independent of the actual implementation.

(IMO, seeing this format will allow us to make a sufficiently informed decision about what framework we want to use (sphinx or a new one with

Edited by dju