WIP: add lib key mini specifications and active proposals to the website

[belluzj]

Start implementing #118 (work in progress, suggestions very welcome!)

Live preview version here: https://daltonmaag.github.io/ufo-spec/extensions/lib_and_data/

I documented three lib keys that are actually Designspace lib keys, and added our Designspace 5.0 proposal.

I chose to allow documenting several lib keys on the same page, because I think it allows for better grouping of information. You can write a common introduction and provide relevant links for all the keys on the page. Then, most of the information about each lib key is structured as YAML. That allows to auto-generate both the "reference tables" for each key and an index page that lists all the keys and provides links with anchors directly to that key's reference table. That index is meant to be Ctrl-F-friendly.

New additions only need to create new files in the _lib_and_data folder, and follow the same organization of the YAML frontmatter (see example file, the "structured" display on Github is not great but I think it looks alright as a basic text file.) The new files will be picked up automatically and added to the index page.

I'm quite happy about that organization, what do you think?

I didn't handle Designspace/UFO version numbers, do you think that it should it be added as a field to each lib key? Or are we going to document only the latest version of the format anyway?

I'm going to keep documenting a few more keys, also some in UFOs libs, and see if I run into any issues with this organization.

As I said I also added a proposal there, I don't remember whether we discussed this, but I think it would make sense to have active/work-in-progress proposals live on the website? The example is our Designspace 5.0 proposal: https://daltonmaag.github.io/ufo-spec/extensions/proposals/designspace-5

[typemytype]

Some comments:

• I think the designspace specifications should be hosted elsewhere, next to the ufo spec. But not mixed in the same repo/website.
• Your proposal makes it hard to determine specific lib keys for specific ufo versions. As lib keys comes and goes, they should be able to move to a public key, to be embedded in a future version or to be removed and abandoned.
• Collecting multiple lib keys on 1 page is counterproductive. Small files, with clear intentions is easier to read and understand then a huge page. But grouping/collecting multiple keys together will make it more readable on overview pages.

Can propose something by the end of the week...

[belluzj]

@typemytype I see that my branch has conflicts, so I'll try to rebase it and also apply some of your comments.

I think the designspace specifications should be hosted elsewhere, next to the ufo spec. But not mixed in the same repo/website.

I'm not a maintainer of either the UFO or the designspace spec. My view on this is that if the UFO spec repository figures out a nice way to host documentation about lib keys, I think it's all benefits and no downsides for the designspace spec to use the same thing; especially since the two formats are so intertwined. I imagine that lib keys from one format will want to link to lib keys from the other; all that would be easier if the two formats were in the same place using the same systems. But, in the end, not my call.

I'll try to add a couple UFO lib keys instead to make this "request for comments" more compatible with your vision of having only UFO stuff here.

Your proposal makes it hard to determine specific lib keys for specific ufo versions. As lib keys comes and goes, they should be able to move to a public key, to be embedded in a future version or to be removed and abandoned.

What if I added a "UFO versions" field to each lib key, with a list of format versions for which this key is valid?

Collecting multiple lib keys on 1 page is counterproductive. Small files, with clear intentions is easier to read and understand then a huge page. But grouping/collecting multiple keys together will make it more readable on overview pages.

To implement this, I could change lib key documentation to force 1 file per lib key, and if we want to write a blurb that describes a bunch of lib keys, I could add an "overview page" as you call it that references several of the lib keys?

What are your proposals on these topics?

[benkiel]

@belluzj I think that @typemytype has been tied up with some things, but he does have a way of handling things that made some sense and dovetailed with your proposal. Let's give him a bit and see if he can get back to his proposal

[benkiel]

@belluzj Understand why you deleted this, but would like to keep this open. We need to get this done, I know it's been dragging out. @typemytype

[belluzj]

I closed this and deleted the branch, since having our gh-pages online was creating confusion compared to the official spec.

[belluzj]

I'll reopen once I have time to rework this to only have the mini-specs more in line with Frederik's comments. Feel free to scavenge commits from the repo here in the meantime if you need to: https://github.com/daltonmaag/ufo-spec