Make a real SPEC, not a description of specifications

[nothingismagick]

trafficstars

If there was a well written spec, then it would be easier to diagnose problems, write external tests and even autogenerate better documentation.

ipfs/interface-ipfs-core/SPEC does an excellent job of this.

[victorb]

Is there something specific missing with https://github.com/ipfs/ipfs-pack/blob/master/spec.md ?

[nothingismagick]

This line is bothersome: "ipfs-pack is only a spec at present, but the hope is to implement it imminently."

Furthermore, the spec.md appears out of date. It is not machine-readable and seems to include commands that never made it off the bench, likeipfs-pack car. Where is PackAuth in my pack?

Please compare the following spec for something more along the lines of what I mean by a SPEC:

https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/KEY.md

[nothingismagick]

This is the way that I feel SPEC driven software design should work:

1. Define a machine-readable SPEC.
2. Derive documentation from the SPEC.
3. Write a generic testing rig that uses the SPEC to create test units.
4. Generate code stubs programatically from the SPEC.
5. Extend stubs until unit tests no longer fail.
6. Along the way define edge cases, extend the SPEC.
7. SPEC extension triggers 2. and 3. and 4.
8. Smooth docs with human authoring and craftspersonship.