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

[gyzki.livejournal.com]

But I suspect it's not going to happen until I have an entire staff of programmers, and can devote some serious time to doing it well.

Programmers yes, and for manuals/tutorials in particular may I strongly recommend a writer/editor. Programmers who think that's the only skill they need, do not help a user who doesn't already know the answer.

[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...)