Hi Krzysztof,
Perhaps I am missing your mark. Ok so we agree on the centralization of the PD help patch.
So you see PDDP as a way or organizing multiple types of documents in a somewhat unified way. Ok.
If we think of a patch as just a patch that is all that it will ever be. A patch could be a document as well though. The main problem I see with having the documentation in different types of media is this linking back and forth part. Abstract concepts, theory, could be more easily represented as a large text-document. I'm not sure if this is the case though, since I personally think theory is best expressed through concrete real-world examples - patches. It is true that things like formulae don't work in PD too elegantly, expr being the most clear representation of an equation, but not all types.
Its the switching back and forth part that makes me wonder about that approach. With examples embeded in the document the way the person reads the document leads back and forth between example and theory, without a mode switch. I can see your idea of linking to static document types work in the case of extra supplimentry information, details on a lower level. Stuff that would scare the novice user.
I guess what I'm thinking is that the ideas are expressed more by example and by experience of the user (as they look at multiple patches) than by a text. This could be off-base. I may just be getting too confused between the tutorial workshop project vs the help system.
Ok I'm going to comment inline for the specific issues...
Krzysztof Czaja wrote:
hi Ben,
<snip>
Those links should directly point to a detailed description (aka reference page, which may actually span several pages), and a ``more info'' story (which may contain math formulae, figures, etc.) The story would link back to various example patches and tutorials.
It is probably only a dream...
Anyway, I feel sorry jumping in the middle of your discussion like some kind of a troll... I was just staring at the main screen of float-help.pd (seemingly an attempt at mimicking Max reference pages by the ``uglier-but-smarter sister''), extrapolating it into xeq-help.pd, and feeling uneasy about:
struggling with an unsuitable editor
Unsuitable in terms of text-editing or editing in general? I think any improvements made to make text-editing easier would also improve the general patching process?
representing my content as Pd global symbols and floats
I see two things, the active content bing the PD patch and its messages, also a text block that is a light overview of theory, not a huge amount of text. I figure it would be half-and-half, text and patch.
storing my content as an unstructured set of bits and pieces
Yes this is true. It is interesting that the talk about comments prepended are actually an effort to structure the comments. What if this went further? I confess I'm not sure how...
giving my screen an ugly look
It does take a bit more effort to make a PD patch look good, but canvases, indentation (using duplicate), and spacing really do help.
not being able to print my content in any reasonable way
"file -> print" not reasonable enough? What if there was a script that converted a folder of patches into a single multi-page PDF?
not being able to publish my content on a web page
About the same anser as above, unless you see a big issue with putting PDFs on web-pages.
I guess I've made it obvious that I think having the text and example integrated into once process (document) is the more advantageous. It is much easier to extend the PD patch format to make nicer documents than it is to make html and PDFs make nice interactive examples.
I'm thinking the final result would be a combination of both ways, with links to supplimentry information as html/pdf/etc documents but the most pertinent information being presented in the patch itself. The latter being easier and most valuable I would say we start with that and go from there.
Should the "hyperlink" object be a toxy widget or an external or an internal? Should it just be part of the [comment] or some new [text] object? hyperlinks inline with comments/text would be pretty familiar to people.
What do we all think?
B.