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

[Mats Persson]

OK, it seems like my comment about the TM users collaborating on the 
documentation hit some right notes.


On 5 Mar 2005, at 00:02, Allan Odgaard wrote:
>> 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 :)

In the above snippet we have the two types of people that are crucial 
to creating a good documentation.
-- The novice (new user) that is not yet understanding the 
app/(whatever) and therefore asks basic questions that other more 
experienced users have learnt/found ways around etc.
--The developer/expert user that knows it all, but would naturally have 
problems understanding the questions arising in the mind of a new user.

The key issue is now how to retain/contain those two key parts as 
efficiently as possible. I think the following would go a part of the 
way towards doing that: (thinking out loud here)

1.	The contents of the current Help Docs is put up on the wiki as a 
starting point, and Allan's documentation outline is implemented.

2.	A registered group of user - like the Bundle Dev's - can then add 
new bits or amend existing bits. Each Doc's Developer could then get an 
e-mail with the latest changes in it like SVN commit messages, or we 
could have a page that shows all those changes only on a single page 
type of thing. Not sure which is best/easiest to do??

3.    The bundled TM Help Doc's is a local copy of the existing online 
docs at the time of release, where on the first page of the Help Doc's 
there is a clear reference to the online doc's and a description of 
what to do when your question has not been answered by the existing 
doc's, i.e. mail your question to the ML or possibly some web form that 
forwards it to the list to save people from joining the ML if they 
don't want to.

4.	The ML or DocDev's would then get the question and instead of 
writing the answer in a reply e-mail, they would write it directly into 
the online docs and then just reply with the link to the answer. That 
way a single action is retained and there is no duplication of efforts, 
and the doc's will grow organically according to actual real user 
needs. Now if Allan or someone else, finds that the answer is incorrect 
or incomplete they could amend the online doc's and resend the reply. 
(Needs a bit more figuring out, but you get the basic idea)

I know that part of that might seem like a bit too ideal, but it's 
really the fastest/best way I can think of. Over to your input ??


As for helping out. Count me in, but due to health reasons I'm not the 
"energetic person to organize the effort".

I already like to have a go at the RegEx section with some real life 
examples and regex translations into plain English for us regex 
challenged individuals ;-)


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

Hmm, I might have misinterpreted your philosophy Allan, but I always 
assumed it to be  "Enabling users to be as productive as they can be no 
matter what code/text they are working with"

But hey, now you've got me really intrigued ;-)


On 6 Mar 2005, at 09:17, Charles M.Gerungan wrote in response to Chris 
Thomas' writings:
>> I guess this is as good a time as any to say that I don't like PmWiki 
>> at all. The site structuring system feels weird; the basic formatting 
>> operators are clunky; the style is not attractive. IMHO. :)
> Agreed. But it's Allen who has to maintain it. (Or is it the users?) 
> Plus, having Tobi on your site and his wilingness to support it is 
> very nice indeed. I envision a fully loaded Hieraki and Tobi creating 
> a "Publish to PDF" button. There you go, a full-fledged manual to be 
> distributed with the application, chapters and all.

Hieraki wins my vote hands down over the existing PmWiki in every 
single aspect I've thought of this far.  (Really nice work there 
Tobias, and if you ever get around to implementing Charles' thoughts it 
will be even sexier !!! )

Not sure how Allan would think of it, but if the users collectively did 
a good enough job, and Allan was always in control over it in the 
background, then I guess he would be happy. I would be at least.

I agree with you Chris, but PmWiki was - I guess - a quick replacement 
for the 'beleaguered' Instiki Wiki. (Sorry, just liked to remind all of 
us 'beleaguered' Mac users of a word we don't hear that often these 
days  :) No offence intended DHH )


Kind regards,

Mats

----
"TextMate, coding with an incredible sense of joy and ease"
- www.macromates.com -