[rdfweb-dev] Blog for project documentation

Danny Ayers danny666 at virgilio.it
Wed Feb 5 12:27:26 UTC 2003

As a bit of an experiment I've set up a Movable Type
(http://www.movabletype.org) based site to manage the dynamic side of
documentation for the Ideagraph project. For material relating to Ideagraph
itself, go have a look.


For the reasoning behind this approach, read on. Here are the aspects I'm
hoping will benefit the project:

* it is very quick and easy to author and publish material

* the reverse chronological order of the blogging style is perfect for
making announcements, and such announcements can be received by RSS feed

* related material can easily be bookmarked

* use of categories allows the separation of posts to provide fairly
transparent site management, for example I've got a category for 'Related
Software' and another for 'Dev Links', it only takes one additional mouse
click for me to place a post/link into one of these categories, similarly
accessing the info in the categories is one click away from the front page
for the reader

* the HTML form based public commenting facility provided by the system
offers Wiki-like contribution by other parties, without the psychological
barrier people seem to encounter when using Wikis. It's easier for
'outsiders' to contribute. Apart from the straight blog-comment approach,
I'm also trying to use this facility in another way. I'm working on a
handful of vocabulary specs, and for each of these I've put a single post in
the blog (these posts can be accessed as a group using the category system).
>From the (static HTML) documentation page for each I've got a link back to
posts within the blog, so anyone viewing the specs is one click away from
adding a comment. Additionally I've set up an area for feature requests/bug
reports, which I'm hoping will be easier for the submitter to use than
full-blown bug tracking software but easier to manage than emailed

* perhaps most significantly in the longer term, the RSS 1.0 feed provided
by the system means that the information added through the use of categories
etc is automatically marked up for the Semantic Web (later on I want to
enrich this content further with inclusion of RDF outside of the RSS
namespaces - to some extent I can already manipulate and organize this
material within Ideagraph). Being able to, for instance, automatically
compile and manage bug reports using loosely couple systems would mean the
computer is doing more work and me less, exactly the way things should be.

I don't see such a system as likely to replace the more static project
documentation (for specs, commercial blurb etc) but for parts where there is
a lot of flux and feedback is required, I think it could be a real
labour-saver. Other tools (such as Maven) that are intended to fulfil this
kind of role seem IMHO to be considerably more technically demanding for the
developer/documentor/administrator, perhaps less end-user friendly and
(currently) lacking the Semantic Web interface.

Anyhow, we'll see how it goes.




"The lyf so short, the craft so long to lerne." - Chaucer

More information about the foaf-dev mailing list