On Mar 4, 2005, at 22:51, Raymond Brigleb wrote:
I agree with the direction this topic is heading though, in that I feel efforts should maybe be more focused on the Wiki, and that needs to start with a structure more like a user manual / documentation.
Yes, Jeroen van der Ham actually suggested that I put the current documentation in the wiki as a starting point.
The current documentation was never intended as a real manual, more like what one couldn't figure out through trial and error -- when I released 1.0 I wasn't sure exactly what people expected from the documentation (and if people actually read that stuff ;) ) -- I do think I have a better understanding of what (those who write me) expect, but how to actually deliver this is very hard.
My approach would be to document the individual features, but I don't think this is really what people want, 90% of these “features” can be seen in the menus, and the behavior of them should be more or less obvious (for the majority of them at least).
The thing people want (as I understand it) is an introduction to how to combine these features to do more than the feature itself. For me that's almost equivalent with having to document e.g. C++ in a way that makes people understand why this is actually an awesome programming language ;)
I did however put down an outline of topics I think would go into a manual: http://macromates.com/wiki/pmwiki?n=Documentation.Main
Hopefully with enough examples this will give the user at least an idea of the flexibility hidden in the program.
I don't know if I'm the person to do it because I'm a complete novice, but I'd surely like to help.
That's actually great, because I've been using computers for so long that I take everything for granted, which makes me rather poor at writing documentation, but good at answering questions :)
With respect to the actual user manual, I just mainly feel that it's missing a beginner's guide / tutorial / philosophy / feature overview kinda thing.
Yes -- I've been trying to write down the philosophy behind it a few times, but there's actually 3 separate goals I've tried to pursue with TextMate, and I always end up making one of these overshadow the other two, which makes me throw it all away ;)
But the next time I venture into this, I'll place it in the wiki!
With something as unique as TextMate, I feel like one needs to hit the ground with some idea of the philosophy behind the text editor. I'm only slowly grasping the unique tricks and workflow of the software.
Although I don't want to hide that the documentation is everything but optimal, one also has to remember that for most new software it just takes time to use the full potential of it :)