This page describes some of the context, goals, tactics, strategies and structurings that should or might be used to make the documentation for TiddlyWeb most useful.

First a little...

History

When TiddlyWeb was first created there was very little documentation. The API and architecture were designed and developed at the same time. The expectation was that TiddlyWeb would be treated as a platform or service with an API and the API would be the major point of interaction. Therefore documenting the API was the major concern and since to some extent (from a twisted point of view) an HTTP API can be considered self documenting, little documentation was created.

TiddlyWeb as just a service didn't turn out to be the case. Many people wanted to use TiddlyWeb as a framework for building server-side applications that present an API. These people, service developers, needed documentation that told them how to:

• Install TiddlyWeb
• Configure TiddlyWeb
• Extend TiddlyWeb
• and perhaps most importantly understand the capabilities of both the architecture and the API.

TPC was created to address that need.

That collection has been somewhat successful but it has a few shortcomings:

• As a TiddlyWiki it can be hard to navigate, browse, index (a la googlebot).
• It is poorly structured, too ad hoc.
• The prose is turgid, jargony and has led to at least one excellent comment along the lines of "wtf are you guys talking about?".
• There's little in the way of excitement or encouragement. Good docs would make a person want to use the product and let them know what it is.
• The information is not well maintained and suffers from being the result of primarily one author.
• Insufficient tutorial or howto information.

What happens is that the documentation fails to effectively reach either of its two main audiences:

• TiddlyWiki users who want a server side. For these people the docs, and TiddlyWeb in general, have often been too confusing, with too little focus. People get overwhelmed, think TiddlyWeb might be cool but is too complex for them.
• Internet folk who want to store content in interesting ways. For these people the docs are too much about tiddlers and TiddlyWiki, bags and recipes. These may be interesting things but they belie or obscure the general applicability and power of the TiddlyWeb system.

Goals

Moving the documentation from TPC to here at TiddlySpace has a few goals:

• Address the shortcomings above.
• Move the content off a personal server belonging to cdent to somewhere faster and more robust.
• Provide an inflection point around which:
  • the content can be refreshed
  • other people can be brought into the process
• Provide dynamic demonstrations that use content in the collection.

Beyond that a critical goal is to make sure that TiddlyWeb is correctly and effectively positioning itself as a useful tool to a large audience. Yes, it is a powerful TiddlyWiki server-side, but it also can be much more than that.

Structure

There are a few aspects to structure:

• Using the documentation and metadata thereon in the creation of dynamic tools such as explorer.
• Providing pathways for different classes of visitors (which overlap):
  • Users of the HTTP API.
  • Server or service admins.
  • Web-app developers.
  • Curious people looking for a data store.
  • TiddlyWiki users who want or need a server side.
  • Reference needs.
  • Overview needs.
• Tutorials
  • Installing
  • Customizing
  • Making plugins
• Documentation in the codebase.

Two existing dynamic tools, explorer and x-doc may provide some guidance for techniques that can be used to help structure information.

explorer looks for any tiddlers tagged httpapi and treats that as a route. Then it uses magic tags to deduce further information:

• Anything beginning with method: describes the methods the current route can handle.
• Anything beginning with rep: describes the serializations the current can handle (in a default installation).

x-doc processes configuration information and reads pydoc in the code to create it's output.

Strategies and Tactics

I (cdent) personally don't want to move the content from TPC to here in any wholesale fashion. That implies that the information over there is good enough, and I don't think it is. It may be that the details are okay, but it is presented poorly.

Sadly there's been insufficient input from the community about what their documentation needs are. If we can generate that information, generating the resulting documentation becomes much easier.

In addition to the task of managing the docs themselves there are some MetaDocsTasks.

Released TiddlyWeb 1.2.59. The main fix was changing when the Cache-Control: no-transform header is being set. It appears it was happening too often, causing browser-side caches to cache representations that would not be validated. Except in special cases (where _cache-max-age header has been set) all resources produced by TiddlyWeb are supposed to be validated all the time. See the commit for a bit more detail on what's going on.

Wrote up some MetaDocs to help contextualize the documentation creation that is gonna happen in tiddlyweb.

Continue explorations of tw5ikifier.

Starting from explorer I filled in some of the documentation blanks. This feels like a somehow more legitimate way of determining what matters in a migration. Or at least motivating.

URL

http://blogs.wsj.com/tech-europe/2012/04/05/one-third-of-o2-staff-say-they-are-more-productive-working-from-home/?mod=WSJBlog

Description

Afterward, the vast majority of staff, 88%, said they were at least equally productive working from home. But, 36% said they were actually more productive.

Date	Users	Spaces	Created	Modified	Tiddlertime	Searchtime
20120301	4617	7210	250	454	291	5163.2
20120302	4626	7222	548	804	289.3	1773
20120303	4636	7232	204	384	286.1	1983.8
20120304	4641	7238	404	616	289.3	3095.7
20120305	4646	7244	329	570	285.1	1868.7
20120306	4650	7250	404	698	280.9	4236.6
20120307	4656	7259	384	622	314.7	3343.2
20120308	4657	7262	294	464	312.7	1875.5
20120309	4661	7269	223	315	312.7	1309.1
20120310	4667	7275	140	255	326.7	4126
20120311	4671	7279	836	990	593	1246.3
20120312	4677	7288	354	705	314	3063.6
20120313	4709	7325	693	1004	310	3171.6
20120314	4717	7333	412	704	318.8	2759.3
20120315	4740	7357	573	708	314	2302.1
20120316	4749	7372	528	705	309.4	2921.8
20120317	4759	7383	201	304	314.8	2022.6
20120318	4765	7390	177	277	311.8	0
20120319	4772	7399	419	524	314.1	1688.1
20120320	4784	7424	810	1041	438.5	2350.7
20120322	4804	7445	0	0	312.6	15584.6
20120323	4814	7457	254	427	309.5	15693.1
20120324	4820	7464	149	236	314.7	15332
20120325	4823	7469	575	674	318	15025.1
20120326	4834	7481	364	809	311.5	15321.7
20120327	4845	7517	830	1068	304.4	15792.1
20120328	4860	7532	223	360	472.1	0
20120329	4875	7553	442	605	301.7	16295
20120330	4878	7561	574	707	827.1	16687.6
20120331	4882	7570	295	443	457.9	1598.1

Figured out how, and then wrote up, how to run TiddlyWeb with nginx and uwsgi.

A bag is a container of uniquely named tiddlers. A bag can have rules for who can edit, delete or read the tiddlers in the bag. These rules are defined in a policy.

A bag may also have a description field, containing text that describes the purpose of the bag or the meaning of the tiddlers contained within.

The combination of a bag's name and a tiddler's name creates the unique distinguishing name for a tiddler on a server.

You can create and manage bags through the HTTP API or with twanager.

See also What is a bag for?.

Attributes

name

The name of the bag.

desc

The description of the bag.

policy

The policy associated with the bag. The default policy allows anyone to do anything with the bag.

A Tiddler is the fundamental piece of content in a TiddlyWiki. You are reading a Tiddler right now. A Tiddler can contain human readable content, data, or javascript code that makes up a plugin, macro or command.

In basic TiddlyWiki tiddlers are limited to living in the one HTML file that makes up the TiddlyWiki. With TiddlyWeb, tiddlers have broader scope:

• They have their own unique URL on the web, which gives them option of travelling around the internet to be used by multiple people in different tools and applications, not just TiddlyWikis.
• They can contain any content at all. If you can represent it with a MIME type and a byte stream, you can put it in a tiddler in TiddlyWeb.

TiddlyWeb was originally created as a reference server-side for TiddlyWiki. This means that its primary job is the storage and provision of tiddlers for use by TiddlyWiki.

The main contribution TiddlyWeb brought to the existing collection of TiddlyWiki server sides was a strong commitment to making the tiddler a first class entity in the system. Everything else in the design comes out of that:

• Each tiddler has its own URI.
• Different tiddlers with the same name are differentiated by being stored in bags.
• Complex collections of tiddlers in bags are assembled using recipes.
• Tiddlers can be selected, sorted and limited using filters.

The upshot of this architecture is that any single tiddler can be reused in multiple different contexts or applications without duplication.

On top of that small number of entities, TiddlyWeb provides a robust web service architecture supporting complex authentication and authorization scenarios, multiple storage engines and multiple output formats. All of which can be extended with plugins.

The Python Package index, found at http://pypi.python.org/. An index and repository of a very large number of third party Python modules.