Re: [DotGNU]WikiTexi (was documentation/manual tool and DotGNU Task List)

[Iain Hallam]

Jonathan P Springer wrote:

 > After the mails that have flown around regarding documentation, I've
posted
 > the result of some research and thinking I did at
 >
 >    <http://members.bellatlantic.net/~vze2mqqv/wikitexi-req.html>


This looks really good, and parallels some stuff that I've been thinking
about (and sketching requirements for) for quite a while. The number of
times I've needed something like this when working on a project are
beyond belief. I like the WYSIWYM (... What You Mean) paradigm, and the
comments I came up with are mainly involved with the way the interface
is presented, but there are a few others in there:

(referring to v1.1)
Functional requirements
=======================
- "Support the generation of additional documentation formats (e.g.
manpages, docbooks, HTML)."

I'd also add a paged format to this list (e.g., PDF). The current set
looks somewhat biased to formats that generate presentation on the fly.

- "Make edit history available for perusal."

And, by extension, available for a full roll-back strategy?

- "Track document initiator..."

Would it be clearer to make that the owner?

- "Provide for importation of existing documents in well-structure
syntaxes (e.g. Linux docs, TexInfo)"

(Above text should say "well-structured") This may be pie-in-the-sky,
but it might eventually prove possible to extract some meaning from
older HTML or Word documents, for those companies/individuals that have
a large investment in existing technologies. This is waaaay in the
future, though... :-)

Commentary and Annotations
==========================
- "The 'Notes' functionality of the PHP Manual provides an excellent
example of such functionality."

   I don't think this is a good UI for notes. I believe that annotations,
   etc. should appear near the text (or images) to which they refer. The
   text says that "each note is associated with a particular document
   node (URI)", which I agree with, but a user should be able to refer to
   something smaller than a paragraph. I'd suggest a .GNU interface that
   puts <span> tags into the text to mark annotations, were it not for
| the fact that elements cannot overlap. Then each annotation could be
| marked with a bar next to the commented lines, much as this scentence
| has been picked out of the containing paragraph. Different annotations
   could have nested bars.

Annotations should also be able to identify the version of the document
that they annotate. If the annotated paragraph disappears in a new
revision, the annotation no longer has much meaning. I think this part
of collaboration needs more investigation.

Document Structure
==================
One thing that might trip up the invisible nature of document
transformations is that each output has different capabilities. It might
be wise to settle on a standard that will be emulated by those formats
that can't otherwise cope. This way, the semantic richness of DocBook
(OK, it's not that rich, but compare it to HTML) could be used as a
base, and then rendered each time to the intended format, but losing the
meaning.

WikiTexi Architecture
=====================
I don't particularly mind what architecture is chosen, but I would
ultimately like something that could use DocBook or some other ASCII
format for basic storage in addition to the RDBMS option. I'd stretch as
far as a UTF encoding on this as well for i18n.

In all, as I said above, I like the approach, and I'd like to get
involved with this (I'm still not profficient enough with .GNU to
contribute fully). I've been thinking about such a beast for a while,
although I had originally envisaged a Java front-end with a WYSIWYM
editor much like a jazzed-up outliner, so I've also got a few ideas on
the UI front.

Thanks,

Iain.