API doc improvements

[shaunlebron]

I spent a few minutes typing this up for our group today with the goal of making the API docs more skimmable:

https://gist.github.com/shaunlebron/27b2339048c8d1746bd1b09ccf52ea7d

Would this be a better format for the API docs, or are there plans for something else?

[janpaul123]

That looks like a good format! Maybe we should just drop that file into the repo and link to it directly (ie. just a github url)?

I do like having it be part of the repo because then we can have PRs that edit both the code and documentation at the same time so they don't get out of sync. What do you think?

[shaunlebron]

Yeah, let's do it. This is easier to modify for PRs for sure.

I'll PR this after adding the last whenPointsAt function to it

[shaunlebron]

Added a PR at #48.

And actually—how are API docs written/shared at Dynamicland?

[janpaul123]

Thanks! In Dynamicland docs are pieces of paper posted in the physical space itself. Both static pieces of paper and interactive tutorial booklets. 🗒

[shaunlebron]

Ah, I think that's a better idea. We should probably throw out the normal computer docs then, and replace with an interactive binder. I think that fits the purpose of this medium to get people off the computer and into the dynamic space to learn about it.

How about a collection of built-in programs for this purpose that can be printed and bound?

[sgwilym]

Being able to print out a starter kit that introduces you to the API of Paper Programs (and maybe even some basic canvas stuff) would be wonderful. @shaunlebron you’re imagining a separate sheet for each part of the API, right?

One thing that runs counter to this a bit is the current state of the print queue UI - I wouldn’t want to rely on it for the printing out of a dozen pages 😬

[shaunlebron]

@sgwilym exactly, some details:

• replace api.md with api.pdf for printing
• generate api.pdf from built-in programs
• api programs are not visible on the print queue
• separate sheet for each part of the API
• multiple copies of api.pdf that allow people to look at them at same time
  • copy built-in programs with new id to prevent clashing

🎥 Dynamicland interactive booklet example

[janpaul123]

What about making the print queue support multi-page jobs? (I always prefer extending existing functionality over writing new code for similar but different features, as it keeps things simple.)