Let's update the spec!

[ianconsolata]

Suggested next steps from the Let's Update the Spec! session at Fil Dev Summit Iceland:

• Spec and an accompanying conformance test suite
  • keeps the standard and implementers honest and in sync
  • example: web platform tests -> every browser engine runs the test suite in CI
  • enables can I use, creates competition between browser vendors, there are always intersection issues, as a user you can only use the intersection of the features in all implementations
• Offer help! How can we decentralized spec maintenance?
• Maybe FIP editors / authors / automated process should make sure that appropriate FIPs have relevant changes to the Spec
• Define what should actually be included in the Filecoin spec, and whether there are subspecs that can be factored out.
  • Modularity allows folks to track updates much more easily.
    • downside is that you need link management to keep the interlinks up to date.
• Should things like market implementation, data onboarding clients, and other protocols be included?
• Crosslink the spec and the code implementation -- add comments in code to relevant spec sections, and add links to code in relevant specs section.
  • Subprojects like builtin-actors should have clear documentation, and link into the spec. It's not only lotus where the implementation lives.
• Don't hesitate to drop things that are really obvious. if it's not needed for documentation purposes because people know it, it can probably be trimmed down so it's more modular.

Link to other places where documentation is happening:

• https://github.com/filecoin-project/core-devs
• https://github.com/filecoin-project/FIPS
• Filecoin docs
• Lotus docs

Action plans:

• @ianconsolata to make issues for each FIP that requires spec updates

[ianconsolata]

Maybe revive https://github.com/filecoin-project/test-vectors?

[smagdali]

I've asked @lanzafame to help out.

Idea one: update the table of contents to be up to date...

[smagdali]

We should update this ticket with our learnings and progress in Bangkok

[ianconsolata]

Stef and I Are trying to come up with a plan for address this feedback. We think the next steps are:

• Find a technical reviewer with understanding of the protocol who can help merge changes and review work. Maybe a review committee, or getting the FIP Editors involved? (requires support outside FF)
• A technical writer or engineer to go FIP by FIP to update the spec (could come from FF)