[TxMt] Documentation (was: Background/foreground colors)

[Allan Odgaard]

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 :)