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 -