High Level Docs

[rylev]

We already have auto-generated API docs. I propose two more kinds:

• High-level overview: These are intended for Rust devs with at least some experience in 2D graphics who would like to explore piet's feature set through prose instead of through examples and API docs.
• The 2D graphics book: This is intended for Rust devs with little to no experience in 2D graphics who would like to learn from scratch using piet.

[raphlinus]

I'm thinking about this. The book idea is appealing but honestly represents too much of a time commitment, I don't see how it's going to happen.

There definitely is a need for a "big picture". There are pieces of it that are still evolving, for example whether text layout is tightly bound to piet or a separate module. I also expect some tweaking as we start retaining drawing sequences into display lists (possibly including building SVG DOM). It feels a bit premature to start going too deep into documentation while the design is still fluid.

One thing I do see happening, though, is blogging. I've pretty much got a rhythm of writing one "big" blog post a week, and a good fraction of those will cover topics in 2D graphics. We can think about how to organize those to make them easily discoverable, as well as links to other useful resources.

[raphlinus]

Also, the podcast I recorded recently with @cmyr does a pretty good job talking about the motivations and structure of the project, though of course it doesn't go into any kind of granular detail how to use the libraries. I have a rough transcript of that and can polish it up as well.

[rylev]

All good thoughts. With the book, I imagined that I would drive that effort. I can start it in its own separate repository, and if it gets to a good place, we can always move it back to this repo. I might even try your idea of blogging about it and then eventually move it into book form if people find it useful.

Let's wait on the "big picture" docs until things get a bit more solid. The podcast and some related prose will definitely go a long way to educate people on the scope and charter of the project.

[raphlinus]

I'm not going to stop you from driving a book, but it's pretty ambitious. I didn't mention this before, but I had strongly considered doing a book around libart. In retrospect, I'm glad I didn't. That design was interesting for a variety of reasons, but ultimately was too tied to the assumptions of software rendering and was also hard to use. I'd like to think I learned from the experience :)

Whatever form this takes, book repo or blog, I'm happy to help.

[bzm3r]

@raphlinus Are there good examples of a high level tutorial of a crate being posted entirely through a blog format?

I would also be interested in helping this effort. I am about to dive pretty deep into piet, so I would be happy to take notes as I progress, which could contribute to a high level docs project?

[raphlinus]

Some examples:

• crossbeam, aturon blog stjepang blog

• futures, aturon blog and others (see also boats)

• embedded rust, japaric blog

There are probably some more, BurntSushi blogs. One thing to check is to go through the top 100 crates and see how many have blogs attached.

And yes, your contributions would most definitely be welcome!