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.