Manual-writing is instructive

[jducoeur]

There's nothing like trying to write a tutorial to show you where your system is still too complicated. I'm currently writing up "Querki for the Impatient", a reasonably flying introduction to the system, and am finding myself adding simplifying enhancements to the to-do list as I go. (The Name vs. Display Name dichotomy *clearly* needs reworking...)

Comments

[jducoeur]

Certainly true, but there reality wins out -- I can't afford to hire anyone, and I'm the only person who knows the system well enough to write the first manuals anyway. So for the first year, I'm pretty much stuck doing it myself. (Fortunately, I am at least better than most programmers at this, although I have my own unfortunate habits.)

Once I can afford to pay people to do stuff, you're correct that a professional writer would be helpful...

[querldox.livejournal.com]

On the other hand, I've always, even before becoming a writer myself, liked that for at least one Wolfram product, they wrote the manual first, before starting any programming.

[jducoeur]

I can respect that, if you have a clear enough idea of exactly what the end result is going to be. Querki is kind of intentionally the other way around, though: I'm experimenting and learning what does and doesn't seem to work in terms of workflow, and a lot is coming out significantly different from my original plans.

(Heaven knows, the QL language is coming out *way* more interesting than I'd originally expected -- achieving a decent measure of DWIM turns out to require a surprisingly powerful language...)