I see PeterThoeny refer to things being in accordance or not accordance with the spec, and I'd like to look at the spec. I suspect that, rather than being documented in one or a few specific documents it is implicitly embodied in a fairly large number of documents like those on the TWiki web?

I tried Google searches on ["TWiki specification"] and ["TWiki spec"] with no useful results (only one hit, on some other TWiki, IIUC. TWiki searches on [TWiki ; spec] return far too many pages to be useful.

-- RandyKramer - 06 May 2003

A lot of the big picture spec is certainly to be found in the TWiki Web. Also specific features are often first agreed in the Codev Web before being implemented - often much of this information makes it's way to the TWiki Web.

-- JohnTalintyre - 07 May 2003

Thanks, John!

I guess (IIUC) that's what I was afraid of — the spec isn't one document but is distributed over a variety of pages on the TWiki, Codev (and maybe the Plugins) webs.

I'm sort of toying with the idea of starting to collect a spec in one place (but probably won't move on it very quickly). Why?

• Maybe it would provide a better understanding to others of how TWiki (and web servers) work?
• If we ever decide to do the old thing of "throwing one away" (I'll get the quote wrong, but something like "plan to write one and throw it away, you will anyway") a consolidated spec might be the place to start.

Anyway, when I refer to "better understanding to others of how TWiki works" I'm:

• including myself among the "others"
• I'm not planning to be terse (see next item)
• I'm thinking about things like the difficulty I had (have) in understanding forms, and thinking I might have been better off to understand that "forms" was not a generic term that I might know enough about from previous knowledge / experience with computers but instead a specific feature of HTML (IIUC) that I should really go and research a little to understand. (I have recently done some of that research, and have a much better understanding.)
• Along similar lines, it would probably have helped me to have an understanding of a web server at an oversimplified level, along the lines of "a web server is a program that can receive requests from a remote program and respond with a stream (?) of specially formatted text (and data, links, whatever) for display in that browser". (In other words, understand some of the magic.)

Would that level of background detail belong in a spec? Probably not — I guess it should be clear that I'd be trying to kill two birds with one stone — documents that provided the background and went on to specify TWiki.

Anyway, I think my question is answered — it looks like the documents for the second do not exist in a concise summarized form (but instead are spread out over the TWiki and Codev webs), so if I want a document(s) like that, I need to create it(them).

PS: I didn't see a good choice (from my point of view) for the TopicClassification — someone may feel free to mark it as they feel is appropriate. (I'm not asking that the developers or anyone else create such a consolidated spec (unless they itch in the same place ), I'm just noting it as one of my itches — will I scratch it???)

-- RandyKramer - 08 May 2003

Putting together a formal spec is a very good idea - go ahead
Putting it all into one document is a bit un-wiki, IMHO.
Granted -- handling many small pages is unpractical for studying the spec. But TWiki solves this dilemma with one of its greatest features:

Use %INCLUDE to pull together the Spec from various existing/new pages like the existing TWikiDocumentation. Use %STARTINCLUDE/%STOPINCLUDEs to pick the core from each topic. E.g. have the formal part on top, then %STOPINLUDE and start with the discussion for this specific topic of the spec. PrintUsingPDF and you can work a 100+ pages document in parallel without any copy & paste & merge & crash woes so common with Office.

-- PeterKlausner - 08 May 2003

Thanks for the encouragement!

I'd hope it would be a collaborative effort (in true wiki fashion).

The other option (if I/we don't need to exclude portions of pages is the BookView search result.

I'll probably start on Wikilearn.TWikiSpec but I have no idea when (I'm more interested in making a change to X at this point in time). The reason to put the spec on Wikilearn: at least initially I expect it to be pretty bad, rambling, incorrect, etc., etc., etc. — not sure it should be anywhere more "official" in that state. When you see the link lose its question mark, you'll know I've started.

-- RandyKramer - 08 May 2003

Perhaps the spec should be done as an appendix to the existing documentation, INCLUDing parts of these as needed. Keeping it up to date could be a challenge - there is not enough work going into the docs as it is.

If people are keen on writing docs, it might be more valuable to first write up some of the new BeijingRelease features in the latest docs - to take just some that I've been involved with, there's a need for TWiki web docs on BrowserIssues, RefreshEditPage and InternationalisationEnhancements.

-- RichardDonkin - 09 May 2003