I published a video about a new kind of documentation: I'm calling it Cognitive Breakpoints, and I'd love to hear your thoughts.
✍️ is challenging because want to communicate a lot of detail to audiences of different backgrounds w/o overwhelming them.
📖 is hard because the author often made assumptions about what know or how deep you want to go.
What if the same document had N levels of depth so the reader could choose how deep they wanted to get into the details?
@semanticart There's something really nice about this idea. Reminds me a bit of Simple Wikipedia or ELI5.
That said there's a lot of teams out there struggling to maintain one version of a document... something something AI.
Is 5 a realistic number of breakpoints? Would 3 make it seem more approachable? Just thinking out loud here.
Anyways, I'm eager to see where you take this. Keep going!
@jqr TYSM for the feedback!
Too-many breakpoints is definitely a concern. I think even 2 breakpoints is an improvement over a single doc. "ELI5" and "Gory details" beats some docs straddling the line. 3 may very well be the sweet spot.
@semanticart During your video, I felt very uneasy, as I always get the feeling that I'd miss something if I kept it at anything but the highest level.
But your JSON-RPC example works really well for me! I think what makes it click is that level 1 to 3 fit on a screen. This way I can easily start at level 1 and move the slider to see what's new.
Keep experimenting 👏😀
(Also, it reminded me of https://www.telescopictext.org/texts/, which I so enjoyed back in the day.)
@peter thanks! Oooh, Telescopic text is cool, I don’t remember seeing it before.
I get the FOMO aspect. 🤔 I think I’ve come to terms with the fact that there’s ALWAYS more to learn. We’re sort of always implicitly picking our depth anyway, but this makes it explicit.
Lots more to ponder here. Thanks again!
Jeffrey Chupp
Elijah Miller
Peter Gassner