Tinderbox User-to-User Forum (for formal tech support please email: info@eastgate.com)
Tinderbox Users >> Off The Wall: Feature Ideas >> Longfrom help documentation

Message started by Johnnie Wilcox - mistersquid on May 24th, 2011, 12:38am

Title: Longfrom help documentation
Post by Johnnie Wilcox - mistersquid on May 24th, 2011, 12:38am

I've been using Tinderbox actively for 5 years now. I know Tinderbox well enough to know it's changed enough to justify an update to the program's standalone, longform, non-networked documentation.

Yes, I'd rather not crawl aTBRef (thanks, Mark A.) for every answer about topics as basic (and intricate) as syntax and method.

Tinderbox deserves standalone documentation that can serve beginners and experts alike. If you must, charge a (reasonable) price for it. Whatever.

I just really really would love something like a user's guide for this Frankensteinian, stitched-together, neo-Vicky pipeworks called Tinderbox which I know, love, and revile at once.


Title: Re: Longfrom help documentation
Post by Mark Anderson on May 24th, 2011, 4:48am

Johnnie, could you give an example sort of question you're looking to answer and the sort of article you're expecting to find? The question's not idle. People regularly articulate what they don't like with the Help but there's nary an indication as to what they envisage in their minds eye.

Over some years of use & helping out I've noted, re Help, that people:
  • don't want long form. Yawn, too much to read in one go.
  • do want long form. Can print out everything in one place.
  • don't want short form articles. Too much clicking around, can't print out in long form.
  • do want short form articles. Allows rich hyper-linking and concise articles on topics.
  • don't want PDF. Inflexible format based on dead-tree technology. Tends to have poor hyperlinking. Doesn't work so well on small screen with limited window space.
  • do want PDF. Rapid word search of whole corpus.
  • do want Help online, outside app. Mac in-app Help slow to load. No word search.
  • want in-app Help. Web access is pervasive than thought. Not all all users live in first-world city areas with fast/always-on access. Some orgs bar on-demand access of their network.
  • want it totally up to date. Conundrum: with a small outfit, delay releases whilst all new features are exhaustively added/reviewed/cross-reference to Help pre-release.
  • want regular releases - qv last item.
  • want to understand how there is no one correct way to do things in TB
  • want to know the one correct way to do things [sic]
  • want to understand incremental formalisation
  • want exact step-by-step of how to implement incremental formalisation
  • want Help to cover everything the app can do
  • dont want Help to cover everything, only 'useful' (?) things
  • want generic examples
  • want very context specific examples
  • want syntax examples
  • don't want syntax examples that don't apply to their particular style of use
  • want exhaustive change logs
  • don't want to have to look at change logs
  • don't want Help cluttered with references to techniques for older versions
  • don't want Help to assume everyone uses the latest version
  • want it comprehensive.  Ensure constant review and re-linking.
  • want small team's limited time that could be spent on app dev being frittered away on writing docs.
  • want an online resource to link to. So updates mustn't break existing doc structure. So, how to add new stuff?**
...and so on, but you get the drift. No model suits all.

**  FWIW, this is aTbRef's ongoing dilemma and why there are three editions still served online. Any significant re-factoring of the source breaks all inbound (web) links and so the doc grows old and ugly via incremental accretion of new stuff.

As someone who's contributed to TB documentation/support in various forms over the years (PDF Help, wiki, forum, Help in HTML form, aTbRef, cookbook...) it's never been clear what people, in an addressable number, want - apart from it not being the status quo.  

Much as I want to like wikis, experience shows few users understand them and without disproportionate effort by attentive wiki gardeners the wikis rapidly become a maze of litter-stewn paths leading nowhere useful. Far from being self-indexing, they rather seem to add to the task of making usable online resources.

The TB Cookbook is a very useful tool but it seems no one uses it, more's the shame.

Leaving aside my involvement, aTbRef encapsulates the inherent conflicts in above listing - it probably gets as many ticks as crosses.

Short-to-long form translation (i.e. such as HTML->PDF) maintaining rich hyperlinking is far less well supported than I'd imagined, having spent a while looking. That app space seems a mix of unsupported semi-documented semi-complete open source projects and Enterprise stuff that you have to be able to afford before you can assess whether their top-$ price ticket is worth it.

I'd certainly be up for getting involved in/doing some new deliberate stand-alone documentation (even better if not for free - groceries cost money!). I'll also be interested to see the publisher's/editor's brief, as I don't think that's yet known, for the reasons above.

Sorry if all this reads as a rant, it's not meant that way. It's just really had to see what what (an addressable number of) users really want.

Title: Re: Longfrom help documentation
Post by Hugh on May 24th, 2011, 5:41am

I've found the "Take Control" Ebooks on Scrivener 2 and DevonThink readable, useful and affordable. Perhaps one could be written about Tinderbox?.

This is whilst recognising the importance of the existing Help (and the difficulties inherent in updating it for such a complex application), the value to users like me and the investment of altruistic effort by Mark A in aTbRef, and the understanding gained from and philosophical significance of The Tinderbox Way.

A word about the Cookbook. I have read it a number of times, but unfortunately without due understanding. I'm grateful for and I acknowledge the effort put into it. But without a less advanced explanation and tutorial (not completely basic, but not assuming any prior coding experience), it's of little utility to me.

Title: Re: Longfrom help documentation
Post by Mark Anderson on May 24th, 2011, 6:09am

@Hugh, funny, I'd had the same thought re seeing a Take Control book for Scrivener.  Though i've not read the latter (I don't have that app) I've several TC books on OS aspects and found them useful. Having a fair degree of in-depth TB knowledge, I'm ambivalent whether within a TC book format everything could be covered. A basics book perhaps with others on Export and on Advanced use (action, code agents). The downside is TB's continuing dev with game-changing additions occurring in minor point releases. This would render some content obsolete or sub-optimal guidance in short order.  The premise of the TC books (and their ilk) is buy-once get update (as long as publication runs). I can see the poor author in a never-ending update cycle. Such is the downside of (electronic) longform documentation of software-  near-instant obsolescence. That said, I'm less agin it than he above comment might imply.

Cookbook? In short the idea is you can go the the web pages and see short code examples of action/export code, to answer questions like "How do I code .sort() with a list?". The HTML pages show working samples, stuff not to try (expected failures) and the very occasional thing that at time of publishing doesn't quite work. Better, you can download the TBX and plug in your own micro tests. Inconveniently, the US uses a different day/moth order in dates from pretty much the rest of the world and with a US publisher and a UK primary contributor, and with day-vs.-month order hard-coded in the examples' code & test strings we're still trying to figure a way to make use locale independent (ideas welcomed!). I'd think using the Cookbook TBX, as opposed to the web output, is more for the intermediate/export user If you want to discuss this more, let's start a new thread in the documentation sub-forum.

Title: Re: Longfrom help documentation
Post by Ben Worthington on May 24th, 2011, 6:49am

Well I would certainly buy the book, but to me by far the most useful learning tool has been downloading precedent files from the Tinderbox File Exchange and, in recent times, from the Tinderbox weekend CDs (plus all the great help here of course).

I think its a real shame that the File Exchange is not more widely used - seeing actual files from other users really fires the imagination in terms of how Tinderbox might be used, as well as showing the mechanics behind the scenes.  Far more useful, in my opinion, than either written material describing this or screencasts (although Stacey has done some very useful screencasts).

I would love to see more templates uploaded (and would be happy to provide my own if these are still being uploaded).


Title: Re: Longfrom help documentation
Post by Mark Bernstein on May 24th, 2011, 8:14am

Regarding sample files and starting points: look for an announcement next week.

Title: Re: Longfrom help documentation
Post by Mark Anderson on May 24th, 2011, 8:44am

Plus, the demos folder of my server has >70 files which will all be linked to from somewhere here in the forums or the wiki. Even if a forum topic under discussion is not close to one's own, it can be instructive to download examples. As most files need the context of the related topic to make sense there's deliberately no plain download listing page though some of the more generic projects ... well, wait until next week.

Title: Re: Longfrom help documentation
Post by Paul Walters on May 24th, 2011, 9:09am

My problem is that there is so much rich documentation available for Tinderbox that I often find myself looking up the answer to a question in aTbRef or the Wiki, then browsing and woolgathering for another half hour learning new things.  ;)

Seriously, aTbRef is amazing, and it's amazing that Mark Anderson is willing to do this day after day, all out of his personal kindness and concern for the Tinderbox user community.  That the source TBX file is available for us to modfiy, refactor, or simply explore using the inbuilt tools and features of Tinderbox itself, is perhaps unique in the Mac domain.  I believe that a Taking Charge book would give little more guidance than The Tinderbox Way, despite its vintage -- although if Mark Bernstein want to update his book I'm already in line to buy it.

Title: Re: Longfrom help documentation
Post by Hugh on May 24th, 2011, 11:19am

I'm very much looking forward to the announcement foreshadowed by Mark B, and will hold back any further contribution till then.

Title: Re: Longfrom help documentation
Post by Johnnie Wilcox - mistersquid on May 25th, 2011, 10:57am

Thanks, Mark A., for your thoughtful and detailed reply.

I understand documentation is hard and pleasing users is even harder. I also appreciate the resources you, in particular, have made available.

My oblique reference to "long-form" documentation was a call for the PDF of yore, something Mark. B. pointed out (via email) continues to be available in Tinderbox's download section. For now, that PDF is keeping me satisfied.

Personally, I think Tinderbox's formidability places the possibility of producing "adequate and comprehensive" (whatever that would mean for any single user or group of users) documentation out of reach of even extraordinary efforts. I honestly can imagine a multi-volume set of documentation for Tinderbox comparable to the JavaScript or PERL books from O'Reilly. I know my own use of Tinderbox might merit a chapter in such a fantasy documentation set and am positive some of the things Iíve seen other users do would be worthy of a chapter grouping or two!

My squeaky wheel noises might drown out my softer assertions that Eastgate and Mark A. have done an excellent job of helping users get up and stay up to speed with Tinderbox by maintaining these forums, Tinderbox's built-in help, aTBRef, and more. So, let me not speak so softly when I say that the resources which do exist are FANTASTIC.

Outside my fantasy of an editorial board and team dedicated to producing a multi-volume documentation set, I know some of the most important resources for Tinderbox come directly from the responsive Tinderbox team members and its lively and engaging user community.

tl;dr: thanks for the PDF version of aTBRef and thanks, everyone, for the thoughtful replies.

Title: Re: Longfrom help documentation
Post by Mark Anderson on May 25th, 2011, 3:37pm

I feel slightly guilty for having suggested the move of the master Help from a Quark doc to a TBX, but it makes it much easier to update as changes often happen close to release. In the background I've made the master doc export both pages - as used by Mac Help - and an a one page HTML with TOC which should be the PDF. But wkhtmltopdf isn't playing ball and there's no support forum.   ;)

So, in the background a long-form doc is in the wings. If anyone's a whizz with wkhtmltopdf, drop me a line off forum.

Tinderbox User-to-User Forum (for formal tech support please email: info@eastgate.com) » Powered by YaBB 2.2.1!
YaBB © 2000-2008. All Rights Reserved.