Use case tutorial
Querki is itself going to need a lot of tutorials. In fact, it is going to need so much tutorial, with such stringent requirements, that I think we may use Querki itself to do some really innovative stuff here.
The key observation is that we can't have a single monumental Tutorial with 75 pages that covers everything, at least not for the normal user -- they'll get scared off. So instead, I believe we will need to structure things around, essentially, recipe books: how-tos that are a modest number of pages, each very task-focused. The goal isn't to teach the user everything about Querki and how it works, but instead how to get what they need done.
The interesting result here is that we want a "tutorial" that is actually made up of reusable building blocks, which we will mix and match in a lot of ways. This will need a lot of mockup and wireframing to get right, but some ideas are clear immediately:
- At the lowest level, we want small bite-size Sections that describe how to do a very specific thing. These might be parameterized to specific problems.
- A How-to Page would be simply a bunch of these Sections, in order, with some custom glue focused on the specific problem at hand. The implication is that How-to Pages would be fairly redundant with each other, but for the layman that's probably ideal.
- Those Sections could also be arranged as one or more narrative Tutorials, aimed at higher-level users who really want to understand the system in more depth. These might be multiple pages, arranged in specialized "trails" a la the Java documentation, which might share Pages in a different order depending on how you're looking at them.
- That, in turn, implies that these pages don't have their order hard-baked into the pages the way tutorials usually do. Instead, there would be Trail objects, each of which has a List of Pages. When you display a Page in the context of a Trail, the URL should carry the Trail as a parameter; we then look up the List in the Trail to figure out which Pages come before and after this one, for the pointers at the top and bottom of the page.
- Finally, there should be a single master Trail, which is the overall soup-to-nuts Tutorial, for the hardcore geek who wants to know how it all works.
This is certainly overkill to start with, but it makes an interesting medium-term problem to play with. In particular, hooking the Trails together would be fascinating: it requires not just URL parameters, but some kind of QL syntax to say "look in Thing X, Property Y, find Z in the List, and tell me what is before/after that". There are probably four distinct, reusable features implied right there.