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

[Jonathan P Springer]

On Mon, Feb 04, 2002 at 09:48:49AM -0500, Rich Hilliard 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>
> | 
> | I'm interested in all of your thoughts, especially wrt additional (or
> | implicit) requirements.  
> 
> I think you have made a great start. A couple comments:
> 
>   * Be fun. (Any suggestions for metrics?)
> 
> Number of downloads of upgrades, number of repeat users.  If something
> is fun to use, people keep using it.
> 

Thanks.  That makes a lot of sense.  I'll work it in.

>   * Allow for additional levels of privileges - document editors,
>     section editors, moderated writers. Moderated writers'
>     contributions must be approved by appropriate section or document
>     editors. (see Collaboration)
> 
> Add "skeleton editors" as a level of privileges above document
> editors.  Hmmm, originally I interpreted "skeleton" as "document
> type", but as I look again, I think you mean more than just the doc type...
> 

I'm breaking out "structural collaboration" vs. "content collaboration."

I really wrestled with the terminology, and I'm still not happy with it.  
The basic train of thought went something like this:

*  There's different ways of representing documents (e.g. DocBook, TexI,
   LinuxDoc) - In SGML/XML this is a "Document Type".

*  There's different types of documents (e.g. Manpages, References,
   Tutorials) - I suppose the right word is "Template"?

*  Some of these document types have set structures and could even be
   pre-populated based on what's being documented.  One could, for
   example pre-organize a library reference based on the function
   prototypes and comments from the library source (a la Javadoc).

What I'm wrestling with is whether the last functionality is within
scope for this project?  The conclusion I'm reaching is that it won't be
in an early release, and if it comes in a later release, it should come
through an import API.

> 
> Under Collaboration, you have 3 levels of "editorial
> responsibility". Do you want to treat document commentary under the
> same mechanism?  Anyone should be able to annotate, comment on the
> document via the collaboration mechanism?  Or maybe this is covered by
> your level Moderated Edits.
> 

*Smacks forehead.*  I'll add a section on annotations and commentary.
They're a separate beast to me because they're not necessarily part of the
document itself.  Instead, they seem to cling to it like sticky-notes.

>  -- Rich Hilliard
> 

Thanks for the input,
-js

-- 
-Jonathan P Springer <address@hidden>
------------------------------------------------------------------------------
"A standard is an arbitrary solution to a recurring problem." - Joe Hazen