d-side / skillforest Goto Github PK

This issue is for tracking useful tips for skilltree authors. This should eventually become a separate page on skillforest's website (I believe it'll have one, considering we're expecting a browser-based client first).

• Favor descriptions over explainations.
• (questionable!) Avoid images
  • they tend to be explainations rather than descriptions
• Keep your skilltree usable offline, embed descriptions, don't link to them

Investigate http://dataprotocols.org/data-package-identifier/ for skilltree URL resolution.

A user (that has already used this system for a while) accumulates a "current state of knowledge", possibly incomplete. This ticket tracks various ways of using this "current state" to make certain conclusions:

• A potential job might have a list of required and useful skills that can be published and rapidly checked against by any client potentially without any involvement from anyone.
• A book might have a list of skills that the author intends its target audience to have. QR-encoding them might provide a possibility to check them with a mobile SF client.

Draft:

{
  "schema": "http://example.com/skillforest/v0.1/schema.json",
  "skills": {
    "skill_1":{
      "name": "Skill 1",
      "description": "Description of skill 1"
    },
    "skill_2": {
      "name": "Skill 2",
      "description": "Description of skill 2",
      "dependencies": ["skill_1"]
    }
  }
}

• name is required
• .skills.<skill>.dependencies, if missing, is assumed to be [], an empty array
• .skills.<skill>.description. if missing, is assumed to be "", an empty string
• A skilltree is considered immutable in that it doesn't change after it's been published.
• Unique identifier for the schema is assumed to be its URL.
• Servers of the skillforest are allowed to have "symlinks", i. e. endpoints that redirect to a certain (e. g. latest) version of the schema. However, since these "symlinks" don't always point to a single version, they must not be used for references.

Not yet considered:

• Skilltree bundling (pack a skilltree with its dependencies into a single file).
• Backup plan in case a skilltree goes down. That could be a list of URLs? Or maybe a map key => URL? key => [URLs]? Looking at how WebRTCs formats evolved, the latter seems preferable.
• Dependencies of the skilltree, not of its individual skills.

This issue outlines progress and notes on the first step of implementing this project

• File structure
  • Title: short and human-readable
  • Key: machine-readable
    • uniqueness is a thing for these, so Java-like domain-name-driven naming (e. g. ru.dside.skilltrees.ruby) might be good candidate
  • Content (markdown?)
    • It's supported on the web (obvisouly!) and in react-native (and won't even hang in RN v0.25+), so... should be "good enough". Best use Commonmark which has a spec and therefore is highly portable.
  • It's just a list of links and references, for the most part. A language that rich is needed to format an explaination.
  • Dependencies: a list of keys of skills a skill depends on: that's for constructing a graph.
  • JSON. Another candidate was YAML, but its only advantage is readability. Since skilltree datasets beg for preprocessing, this isn't really an advantage.
• Static visualizer/viewer
• Validator
  • Markdown being valid (not sure if there is such thing as invalid Markdown, but gotta check)
  • Skilltree acyclicity
  • Key uniqueness (not using JSON would be a pain, it seems, so it's necessary)
• Stateful visualizer