Referring back to Is there a way to send the freq value from a pbind to Processing? - #12 by jordan – this post raises several issues about SCDoc vs the requirements of documenting streams-patterns-events.
One major issue is that SCDoc indexing is heavily biased towards class/method documentation, while the default event prototype is just a data structure and not indexable this way.
I’ve argued for a long time that a significant gap in SC documentation is what I’d call “topic” documentation. IMO the linked post is calling attention to this, but reaching (again IMO) the wrong conclusion. (“A Practical Guide to Patterns” was an attempt at topic documentation… but… “if it doesn’t come up as a result of the search in the help browser when looking for specific terms (Event, Event Types, Pbind, callback…), it might as well not exist.”)
It’s a good thing that the default event prototype is a “soft” structure – you can extend or modify at runtime, without recompiling the class library. The suggestion in the linked post is that we should remove this flexibility, and force all event types to be hard classes, because of SCDoc’s poor indexing of non-class documentation. Well, I’m going to have to disagree with that. If the problem is that it’s difficult to search for documentation that is not about classes or methods, then the solution is to improve the search features!
We should definitely not be making programming-interface design decisions based on the documentation system’s strengths and weaknesses. The documentation system should serve the language, not the language serving the documentation system.
So one purpose of this thread is to brainstorm ideas to improve SCDoc indexing, so that topic documentation can be as easily accessed as class documentation.
One simple approach that wasn’t even considered is – thorough linking. We already have a document that exhaustively lists the keys in the default event prototype (but “it might as well not exist” because it isn’t searchable).
What if every help file related to the default event prototype (Event, Pbind etc.) contained a prominent link to the existing document?
I’ll have to wrap up shortly, but I’d like to finish with one observation from my experiences a few years ago preparing some scores in LilyPond. LP’s documentation is exhaustive, thorough and generally excellent – and it takes a long time to learn where things are in it. From this, I came to suspect that there may simply be no way around the problem of building a mental map of the documentation. Improving search features can help to alleviate this problem, but they cannot eliminate this problem. Agree with Jordan that there are things we can do to make it easier.