Proposal: Move http://tiddlywiki.org to TiddlySpace
chris...@gmail.com
The wiki at http://tiddlywiki.org/ is MediaWiki, not TiddlyWiki. This
has always been a bit of an embarassment. That wiki is also subject to
spam that without constant attention can get a bit out of hand.
When the wiki was created multi-user platforms for TiddlyWiki were a
bit thin on the ground. Now, with TiddlyWeb and TiddlySpace there is
an actively maintained multi-user platform that can easily support the
documentary purposes of the wiki.
So I'd like to propose that we being a process of migrating the
content of http://tiddlywiki.org to a space or collection of spaces on
http://tiddlyspace.com/
If people have concerns, objections or encouragement, please post
here. This is not a done deal, just a proposal, but the benefits seem
a win:
* Using tiddly-dogfood for Tiddly things
* TiddlySpace can be configured to allow members-only editing to
prevent spam.
* The TiddlyWeb API underneath allowing multiple mode of editing,
reuse and mashing up.
If as a group we decide to move forward with this proposal, then I
would like to suggest the follow migration style: Rather than automate
some process of copying all the content from the mediawiki server to
TiddlySpace, I think it would be far better to move content by hand
and piecemeal, leaving behind references to the new content and
editing the content as it is put into the new system. This provides a
structure upon which we can, as we do it, refresh all the content. And
a refresh is badly needed.
Thoughts?
--
Chris Dent http://burningchrome.com/
[...]
colmjude
Agree that we should us the migration to refresh and improve the
content.
Also feel that it would make sense to use a strength of TiddlySpace
and separate out content in to different spaces.
In some instances where we thought we were lacking content/
documentation this has started to happen. The following spaces are
being worked on and include both TiddlyWiki and TiddlySpace content,
with it all being pulled together in docs.tiddlyspace.com:
tiddlywikidev.tiddlyspace.com
macros.tiddlyspace.com
shadowtiddlers.tiddlyspace.com
wikitext.tiddlyspace.com
faq.tiddlyspace.com
Cheers,
Colm
On Jan 20, 1:18 pm, chris.d...@gmail.com wrote:
> The wiki athttp://tiddlywiki.org/is MediaWiki, not TiddlyWiki. This
> spam that without constant attention can get a bit out of hand.
>
> When the wiki was created multi-user platforms for TiddlyWiki were a
> bit thin on the ground. Now, with TiddlyWeb and TiddlySpace there is
> an actively maintained multi-user platform that can easily support the
> documentary purposes of the wiki.
>
> So I'd like to propose that we being a process of migrating the
Julian Knight
passingby
shall rejuvenate the documentation process.
Alex Hough
best wishes
Alex
GIT as well? Every cool project is on there now. As a TW user who learns everything about web technology though TiddlyWiki would be great to learn about GIT as well.
I've always found it rather odd too. It should be a showcase and example of excellence for TW.
--
You received this message because you are subscribed to the Google Groups "TiddlyWiki" group.
To post to this group, send email to tiddl...@googlegroups.com.
To unsubscribe from this group, send email to tiddlywiki+...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/tiddlywiki?hl=en.
FND
> I don't see anything wrong in moving to tiddlyspace. If anything it
> shall rejuvenate the documentation process.
Indeed, such a move would be quite welcome for the reasons stated.
However, having been the primary/sole maintainer of tiddlywiki.org until
recently, I've learned that diligently tracking changes is important.
Granted, this might be more important to me than for others (OCD and
all), but it still seems essential in this case.
While I'm no fan of MediaWiki in general, its recent changes feed[1] has
proven extremely useful.
TiddlySpace/TiddlyWeb does not yet have adequate (IMO) facilities for
efficiently and effectively tracking changes in detail. While three's
some experimental support for diffs in TiddlyWeb feeds, in my experience
that's very rudimentary[2] at this point (for a variety of technical and
conceptual reasons).
Obviously such concerns can be dismissed for those not suffering from
control issues, paranoia and misanthropy... It won't affect me directly
anymore, so I'm just sharing my experience - for science.
-- F.
[1] http://tiddlywiki.org/index.php?title=Special:RecentChanges&feed=atom
[2] e.g. no guarantee that every single revision will show up, visual
presentation is far from ideal, no convenient undo/rollback
chris...@gmail.com
> GIT as well? Every cool project is on there now. As a TW user who learns
> everything about web technology though TiddlyWiki would be great to learn
> about GIT as well.
http://groups.google.com/group/tiddlywikidev/browse_thread/thread/9cb07c23178a03fb
HansWobbe
> If people have concerns, objections or encouragement, please post
> here. This is not a done deal, just a proposal, but the benefits seem
> a win:
>
of TiddlySpace. -- HansWobbe
Julian Knight
Tobias Beer
people organize content and efforts in such an
undertaking ...TiddlyWeb style.
Quite possibly demands will come up that give rise to whole new
dimensions or simply emphasize existing ways of how TiddlyWiki /
TiddlyWeb can be a big leap forward in the area of what might be
understood as shared knowledgemaps ..those that are well defined in
scope.
Also, loads of documentation and related content already has been or
is being ported to TiddlySpace. So, the documentation space might not
even be something to reinvent the wheel but only providing the most up
to date pointers into a desired direction, without overly stretching
topics into much too detailed showcases.
So, I would say this proposal indeed is the way to go...
Cheers, Tobias.
passingby
basis for creating a history? Would that make up for it? Of course
that would not save every revision, but just a snapshot of the moment.
chris...@gmail.com
> How about archiving the tiddlyspace documentation offline on regular
> basis for creating a history? Would that make up for it? Of course
> that would not save every revision, but just a snapshot of the moment.
It's not that the history doesn't exist, it's that the tools for
accessing it don't provide the "rich" experience that some wikis
provide. See, for example,
Those are the three revisions of that tiddler.
chris...@gmail.com
> Quite possibly demands will come up that give rise to whole new
> dimensions or simply emphasize existing ways of how TiddlyWiki /
> TiddlyWeb can be a big leap forward in the area of what might be
> understood as shared knowledgemaps ..those that are well defined in
> scope.
To get the ball I've adjusted and existing space and created a new one
on TiddlySpace:
* http://tiddlywiki.tiddlyspace.com/
* http://tiddlywiki-meta.tiddlyspace.com/
The first one is where the content will go. The second one is for
discussion about the content or how to manage the content, the process
of migration, and otherwise get on with things.
I have adjusted the policies in those spaces so that anyone who is a
member of any TiddlySpace will be able to make edits. If you would
like to participate in the planning in @tiddlywiki-meta or migration
to @tiddlywiki and do not yet have a Tiddly space, go to http://tiddlyspace.com/
to sign up.
We'll improve things as we go along. Looking forward to it.
Poul
> So I'd like to propose that we being a process of migrating the
> If people have concerns, objections or encouragement, please post
> here. This is not a done deal, just a proposal, but the benefits seem
> a win:
>
tiddlyspace.
The pros and cons executive summary goes something like:
+ Better revision control, including diff and revert
+ Recent changes, recent comments, tree structure, SiteMap, page
templates, etc.
- It's currently a fork of TW 2.4.1
+ It's only 320K before content, as compared to 770K for TiddlySpace
+ It's cloud-based, which means Google will host it on redundant
servers for little or nothing.
The one major piece still missing is server-side search (I have my
eyes on Whoosh-AppEngine for that solution). I don't know what
TiddlySpace has to offer in this department.
Jeremy Ruston
self-contained TiddlyWiki comprising the content of any space. The
idea is that any community member with the will has the means to take
their own backups by scripting regular downloads via shell scripting,
windows shell, Mac Automator etc
Best wishes
Jeremy
--
Jeremy Ruston
http://www.osmosoft.com/
chris...@gmail.com
> I - of course - must recommend giewiki as an alternative to
> tiddlyspace.
I think it is great that there are plenty of options, but this
message seems like an invitation to respond with some compare and
contrast, perhaps so all systems can improve, so here goes:
> The pros and cons executive summary goes something like:
> + Better revision control, including diff and revert
This is a "simple matter of programming" at this point. Perhaps there
is code in giewiki that can be borrowed? TiddlyWeb (the guts
underneath TiddlySpace) stores revisions but does not provide in
itself tools for diff and doing revert. That's taken as the
obligation of the client side: TiddlyWeb provides the storage api.
> + Recent changes, recent comments, tree structure, SiteMap, page
> templates, etc.
Ditto on the above. TiddlyWeb lets you use whatever tools you want
for doing those kinds of things. If you have tiddlywiki plugins
which do those things, magic.
> - It's currently a fork of TW 2.4.1
tiddlywebwiki, the package the includes the empty.html used with the
wiki serialization tracks the latest stable release. TiddlySpace
itself has functionality that allows a request to optionally use
whatever the latest beta TiddlyWiki is.
> + It's only 320K before content, as compared to 770K for TiddlySpace
Yeah, this is a big problem with TiddlySpace. On a plain
tiddlywebwiki it's 421K, which is still too much.
> + It's cloud-based, which means Google will host it on redundant
> servers for little or nothing.
TiddlyWeb can run on app engine[1] just fine, and it would be no big
deal to make TiddlySpace do the same. It's been useful thus far to
have it on its own server for the sake of tweakability.
All that said I think the biggest win for TiddlyWeb (and excuse me
if giewiki has this stuff too, I had a look round the code but it
wasn't immediately obvious) is that it is explicitly designed to
make Tiddlers first class entities on the web. They have their own
URIs, can be represented in multiple (and extensible) content-types
(common ones are text, json, in-a-tiddlywiki, html and atom), can
contain any content (including images) not just wikitext, and
can be reused, by reference, across multiple wikis or other collections.
TiddlyWeb makes very few assumptions about how those tiddlers are
going to be used and who is going to use them. It's proven quite
remarkable, actually, taking the tiddler concept out of tiddlywiki
and thinking of them as free floating bits of content.
That makes it very flexible, but also means that it does not have
the level of focus that giewiki has: "giewiki tries to be a real
wiki". [3]
In specific context of tiddlywiki.org, right now I think the winning
proposition for TiddlySpace is the inclusion functionality that allows
the content to be distributed across multiple spaces. I've already include
the tiddlywikidev space into the tiddlywiki space, meaning that a large
collection of developer oriented content (mostly explaining available
methods in the core) is just there.
> The one major piece still missing is server-side search (I have my
> eyes on Whoosh-AppEngine for that solution). I don't know what
> TiddlySpace has to offer in this department.
We experimented with plain whoosh for tiddlyspace[4], but versions
prior to 1.9 had some pretty severe concurrency problems, so have
ended up using the fulltext indexing in mysql. This has ended up
working out quite well as most of the searches that people want to
do are field based, and thus use column indexes, not the fulltext
index. A parser, modeled on the one in whoosh, compiles[5] queries
to SQL.
[1] http://cdent.tumblr.com/post/278948050/smooth-tiddlyweb-on-app-engine
http://cdent.tumblr.com/post/283065885/tiddlywebweb-to-app-engine
[2] For a simple example of tiddlers out of tiddlywiki context, I use
tiddlers as a sort of twitter, and then present them on my homepage:
http://burningchrome.com/ using a simple bit of javascript (itself a
tiddler) to get a JSONP representation of those tiddlers:
http://twpresent.tiddlyspace.com/twpresent.js
That stuff is described at http://twpresent.tiddlyspace.com/
[3] http://code.google.com/p/giewiki/
[4] https://github.com/tiddlyweb/tiddlywebplugins.whoosher
[5] https://github.com/cdent/tiddlywebplugins.mysql/blob/master/tiddlywebplugins/mysql2.py#L232
Poul
> On Tue, 25 Jan 2011, Poul wrote:
> > I - of course - must recommend giewiki as an alternative to
> > tiddlyspace.
>
> I think it is great that there are plenty of options, but this
> message seems like an invitation to respond with some compare and
> contrast, perhaps so all systems can improve, so here goes:
>
> > The pros and cons executive summary goes something like:
> > + Better revision control, including diff and revert
>
> This is a "simple matter of programming" at this point. Perhaps there
> is code in giewiki that can be borrowed? TiddlyWeb (the guts
> underneath TiddlySpace) stores revisions but does not provide in
> itself tools for diff and doing revert. That's taken as the
> obligation of the client side: TiddlyWeb provides the storage api.
server-side though.
I probably don't understand TiddlyWeb well enough to say for sure, but
my immediate reaction would be to observe that a web arcitecture that
leaves all kinds of application-level duties to the client is going to
be a very insecure one - just as you wouldn't expose SQL directly to
the client. I'm not saying that giewiki scores high on security, but I
am taking a more pragmatic approach when it comes to placing the
detailed responsibilities. The main reason I did giewiki is that I
felt that so much could be achieved by combining TiddlyWiki with a
server-side, which wouldn't be appropriate to client-side.
>
> > + Recent changes, recent comments, tree structure, SiteMap, page
> > templates, etc.
>
> Ditto on the above. TiddlyWeb lets you use whatever tools you want
> for doing those kinds of things. If you have tiddlywiki plugins
> which do those things, magic.
>
giewiki, for reasons of security and performance.
> > - It's currently a fork of TW 2.4.1
>
> tiddlywebwiki, the package the includes the empty.html used with the
> wiki serialization tracks the latest stable release. TiddlySpace
> itself has functionality that allows a request to optionally use
> whatever the latest beta TiddlyWiki is.
>
> > + It's only 320K before content, as compared to 770K for TiddlySpace
>
> Yeah, this is a big problem with TiddlySpace. On a plain
> tiddlywebwiki it's 421K, which is still too much.
>
The second was that my first attempt used unmodified TW 2.0.x code,
only to find that later changes to TiddlyWiki broke my code.
> > + It's cloud-based, which means Google will host it on redundant
> > servers for little or nothing.
>
> TiddlyWeb can run on app engine[1] just fine, and it would be no big
> deal to make TiddlySpace do the same. It's been useful thus far to
> have it on its own server for the sake of tweakability.
>
> All that said I think the biggest win for TiddlyWeb (and excuse me
> if giewiki has this stuff too, I had a look round the code but it
> wasn't immediately obvious) is that it is explicitly designed to
> make Tiddlers first class entities on the web. They have their own
> URIs, can be represented in multiple (and extensible) content-types
> (common ones are text, json, in-a-tiddlywiki, html and atom), can
> contain any content (including images) not just wikitext, and
> can be reused, by reference, across multiple wikis or other collections.
(plus a GUID to allow stronger identification), although currently you
cannot retrieve a single tiddler. I'm not saying that the currently
available modes of retrieval are all that anyone could want, though.
>
> TiddlyWeb makes very few assumptions about how those tiddlers are
> going to be used and who is going to use them. It's proven quite
> remarkable, actually, taking the tiddler concept out of tiddlywiki
> and thinking of them as free floating bits of content.
twenty plugins from different servers, it's going to have an impact on
performance. giewiki addresses this problem by caching copies of the
content that you include, then builds a page template mechanism along
the same lines.
>
> That makes it very flexible, but also means that it does not have
> the level of focus that giewiki has: "giewiki tries to be a real
> wiki". [3]
>
> In specific context of tiddlywiki.org, right now I think the winning
> proposition for TiddlySpace is the inclusion functionality that allows
> the content to be distributed across multiple spaces. I've already include
> the tiddlywikidev space into the tiddlywiki space, meaning that a large
> collection of developer oriented content (mostly explaining available
> methods in the core) is just there.
another. giewiki has that too, although currently only by reference to
the specific set of tiddlers that you want to include. Problems seem
to arise when you want to include all (current and future -if that's
what you do) because of namespace collision and confusion (to the
reader) of context and conflicting use of terms (Accidental/automatic
links may be great, but I'm not sure they are helpful without human
sanity checks). Actually, such inclusion is to me something that
should be left to the discretion of the reader.
All in all, I think the best route would be to leave the choice of
future platform to someone with an unbiased point of view.
/Poul Staugaard
Poul
On 29 Jan., 01:36, Poul <poul.stauga...@gmail.com> wrote:
> All in all, I think the best route would be to leave the choice of
> future platform to someone with an unbiased point of view.
unintentional (really) implication:
I'll be perfectly happy to accept the decision of the community, if I
feel that it has been made through an open, transparent process.
Martin Budden
future platform to someone with an unbiased point of view."
feel that it has been made through an open, transparent process."
To make an unbiased and transparent decision we need to set down the
criteria for the decision and then evaluate the alternatives against
those criteria. I suggest the following criteria (and feel free to add
to this list):
i) New host must support TiddlyWiki formatting and macros (which one
of the main reasons to move away from MediaWiki)
ii) New host must be multi-user (which is why we cannot just use a
TiddlyWiki)
iii) New host must be based on an established and supported platform
(long-time users of TiddlyWiki may remember that the documentation,
prior to mediawiki, was on ZiddlyWiki, a Zope-based server side
TiddlyWiki. We moved away from this because the Zope server we used
shut down and ZiddlyWiki stopped being supported by its author).
iv) New host must be reasonably fast and responsive.
Martin
rakugo
v) New host must be reliable and maintained (I don't want any
downtime!)
vi) Access to revisions
vii) Running latest version of TiddlyWiki at all times - important for
the "this is a tiddlywiki thing". If we are going to run something
which is an old version of TiddlyWiki, to me it defeats the point of
moving from MediaWiki
viii) An api / url for each individual tiddler so that the community
can make mash ups, run their own media wiki instance etc.. I don't
want a closed system where it's hard to get stuff out of.
ix) Pages should be downloadable so they can run offline - I might
want to download some documentation on a certain subject to use on the
train for example.
Jon
chris...@gmail.com
> "All in all, I think the best route would be to leave the choice of
> future platform to someone with an unbiased point of view."
> "I'll be perfectly happy to accept the decision of the community, if I
> feel that it has been made through an open, transparent process."
>
> I'll make some effort to start that off:
ahead and started work on moving some content into http://tiddlywiki.tiddlyspace.com/
If this proves to not be the correct place, then since the content is
stored there in TiddlyWiki form, as well as accessible as structured
JSON, then it will be easy enough to move it if people feel like it.
Thus far I have only primed the pump with just a few pages moved in.
Anyone who has an account on http://tiddlyspace.com/ is able to edit
in that space. Please feel free to add and edit content. This is a
community resource and as such, it can only be good if the community
contributes.
Also, this is an iterative process, so there is no need for it to be
perfect right away. We will make it perfect as we work.
Once there is a sufficient amount of content in the new location,
http://tiddlywiki.org/ will be redirected to the new site.
Thanks.
PMario
> As its been a week since this posting and little discussion, I've gone
> ahead and started work on moving some content intohttp://tiddlywiki.tiddlyspace.com/
> Anyone who has an account onhttp://tiddlyspace.com/is able to edit
> community resource and as such, it can only be good if the community
> contributes.
*tiddlywikidev
*glossary
I wanted to add some info to eg: http://tiddlywiki.tiddlyspace.com/#getWeek%28%29
Then I saw, that I created a clone, since it is part of tiddlywikidev
space. Now I have the problem, that you mentioned some time ago. I
have no problem to switch the space for editing. I just don't want to
create a second/cloned version of it. IMO open up the wiki stuff. All
or nothing.
-m
chris...@gmail.com
> I wanted to add some info to eg: http://tiddlywiki.tiddlyspace.com/#getWeek%28%29
> Then I saw, that I created a clone, since it is part of tiddlywikidev
> space. Now I have the problem, that you mentioned some time ago. I
> have no problem to switch the space for editing. I just don't want to
> create a second/cloned version of it. IMO open up the wiki stuff. All
> or nothing.
Don't worry about creating clones in these sorts of situations. If the
maintainers of @tiddlywikidev are paying attention they will see your
clone as part of the activity and following process and will integrate
your changes if they like them.
This is _exactly_ how it is supposed to work when it comes to human
readable stuff in TiddlySpace. It's a large part of how the
discoursive sociability is supposed to work.
Obviously there are still many rough spots, but we will find them and
fix them by doing what seems natural, finding the mismatches between
that and how the system works.
As you might recall, this is a bit of a change in tune on my part:
Originally I wanted to avoid unnecessary clones, but now I think,
given the diverse types of membership and inclusion that will be
present in a large TiddlySpace system, its more important to be able
to _manage_ clones rather than _avoid_ clones.
The mechanism of that management remain to be seen.
Tobias Beer
Would it be reasonable to create a kind of "inventory" of
tiddlywiki.org then have that listed along with a migration status and
maybe comment fields per entry (to add links, etc.) ... just to get
things "moving" in an organized fashion?
This way, people could know what has already been ported and what
hasn't (or why) ...in order to eventually be able to assess when a
kind of "initial setup" is sort of completed. I mean, how many
articles or how much content are we even talking about?
Tobias.
chris...@gmail.com
> Would it be reasonable to create a kind of "inventory" of
> tiddlywiki.org then have that listed along with a migration status and
> maybe comment fields per entry (to add links, etc.) ... just to get
> things "moving" in an organized fashion?
I'm hesitant to get to overly embroiled in formalzing a process for
the migration. It's just text in wiki pages after all and it is in one
of two states, from what I can tell:
* not very good, as there's no invested party, so moving it can just
happen as it does and the gaps will get filled in as they need to
* very good, with an invested owner of the content, so that owner is
likely going to be on the case
What's missing right now is some indication on the pages that have
already moved that the migration has started. This is pretty much my
fault and I will attempt to fix that as I move forward with additional
page transfers
> This way, people could know what has already been ported and what
> hasn't (or why) ...in order to eventually be able to assess when a
> kind of "initial setup" is sort of completed. I mean, how many
> articles or how much content are we even talking about?
It's not that much, so as long as people mark an already moved page,
it should be pretty clear how it is going.
What's more important than moving, I think, is being good gardeners of
the content after it has moved. My hope is that we can keep enthusiams
percolating nicely so that even a year from now the content in the
space is being actively updated.
colmjude
On Feb 13, 2:48 pm, chris.d...@gmail.com wrote:
> On Fri, 11 Feb 2011, PMario wrote:
> > I wanted to add some info to eg:http://tiddlywiki.tiddlyspace.com/#getWeek%28%29
> > Then I saw, that I created a clone, since it is part of tiddlywikidev
> > space. Now I have the problem, that you mentioned some time ago. I
> > have no problem to switch the space for editing. I just don't want to
> > create a second/cloned version of it. IMO open up the wiki stuff. All
> > or nothing.
>
> Don't worry about creating clones in these sorts of situations. If the
> maintainers of @tiddlywikidev are paying attention they will see your
> clone as part of the activity and following process and will integrate
> your changes if they like them.
make and we hope people will.
The @tiddlywikidev space uses the same mechanism that the @interview
space uses so people's suggested changes will show up in a comment
like fashion.
See:
http://tiddlywikidev.tiddlyspace.com/#getWeek%28%29
Plus we would encourage anyone to create content that they think
should be part of the @tiddlywikidev space and currently isn't.
See
http://tiddlywikidev.tiddlyspace.com/#[[TiddlyWiki%20Dev%20Missing%20Stuff]]
Colm
Tobias Beer
I didn't mean to ask for a somewhat tight or rigid workflow ...rather
a means of orientation. I understand that there are authors and
maintainers of articles, yet I doubt they themselves have an overview
of the articles in concern or even are aware of the migration process.
So, if there were an easy enough way for MediaWiki to provide us with
an initial list, maybe with author, last modifier, modified date,
categories, etc... I think that would at least give a good indication
and some stats for orientation.
Whether that is being used or even considered would of course be up to
everyone contributing. But it would definitely give a neat reference
of topics up until this day.
Or, how about dumping all MediaWiki content into text chunks and then
import the lot into an initial TiddlyWiki? I am not a MediaWiki tech-
literate, so this is at best brainstorming.
Cheers, Tobias.
chris...@gmail.com
> So, if there were an easy enough way for MediaWiki to provide us with
> an initial list, maybe with author, last modifier, modified date,
> categories, etc... I think that would at least give a good indication
> and some stats for orientation.
The tiddlywiki mediawiki will show all the pages via links from this
page:
http://tiddlywiki.org/wiki/Special:RecentChanges
which doesn't really do you much good.
> Or, how about dumping all MediaWiki content into text chunks and then
> import the lot into an initial TiddlyWiki? I am not a MediaWiki tech-
> literate, so this is at best brainstorming.
I'm not inclined to do this, even if I knew how (I don't, off the top of
my head) because I believe that this moment presents a unique
opportunity to have a human's eyes upon the content as it is migrated.
By _not_ automating the process every single page will get at least a
little bit of attention when it is moved.
The process I'm using at the moment is this:
* I look at a tiddler in the target site for a missing link.
* I go to the source site and copy the wikitext for the page with the
name of that missing link.
* I paste that into a tiddler with the name.
* I correct the formatting so it looks correct in TiddlyWiki.
* I make a link on the source site to the new tiddler, with title
"Migrate".
Anyone else can use this process too. I hope they will. Eventually all
the content will be moved over. Or if not, then the content isn't
particularly useful.
Obviously this is rather time consuming, but the consensus in this
group has been that effective documentation is important.