[Fwd: Re: in the so crazy it just might work department]

[Shaun McCance <shaunm gnome org>]

I'm so forgetful.  Forwarding to gnome-doc-list.

> On Sat, 2004-04-17 at 00:49 -0500, Shaun McCance wrote:
> > On Fri, 2004-04-16 at 19:03 -0400, Luis Villa wrote:
> > > Just had a sort of sit down with an Apache guy, and talked briefly about
> > > help systems, and had a sort of brainstorm from some of his comments.
> > > 
> > > What if a help system were more like a wiki?
> > > 
> > > Like, instead of or as a supplement to a big monolithic doc, what if
> > > individual windows had help buttons, and if you toggled a gconf key, or
> > > were using a devel build, you could edit the current text (if there was
> > > any) and submit the diffs/new content to bugzilla or (better) some kind
> > > of central doc server where people could grab automatic updates from,
> > > and where tarballs could be built from for non-devel builds? You could
> > > take the idea farther, possibly, creating a web of nodes, not just one
> > > stand-alone one per dialog/window. And maybe you could scan new content
> > > to make sure it didn't make 'common' terminology mistakes?
> > > 
> > > Stefano's point was that we know from blogs and email that people are
> > > happy to write simple, quick text, and/or edit the text of others, and
> > > he thinks that principle could really apply to docs (though he was
> > > originally referring to indexing email lists to create API docs, which
> > > was a totally different but also cool idea.) And it seemed self-evident
> > > that if this is true, and if wiki's work (more or less), maybe we can
> > > break docs down into smaller bits and parallelize the hell out of it.
> > > 
> > > Is this insane?
> > 
> > So there are two topics here, one of which I view as more fundamental.
> > The first is how the docs are logically organized.  I'm not just talking
> > about getting docs registered and such.  I'm talking about the paradigm
> > we actually use to present the docs.  Currently, our documentation is
> > very document-oriented.  We have the GNOME User Guide, the gedit Manual,
> > etc.
> > 
> > Users generally do not read documents cover-to-cover.  They pull up the
> > topic for whatever task they're doing.  Anybody who's seen my proposal
> > for my GUADEC talk or who's spent time with me on IRC will have seen me
> > use the phrase "topic-oriented help".  The general principle is that we
> > provide help as digestible topics, with nice semantic linking between
> > them all.  There are ways of making this work, and I'd love to be doing
> > it.  As with everything, it's a matter of how much time I can find.
> > 
> > The other thing is having the ability to edit documents easily.  Being
> > able to submit changes and stuff is trivial.  In fact, I've considered
> > adding bug reporting capability to Yelp (probably only for development
> > builds).  What we need here is a good structured document editor, which
> > is another phrase you'll see in my GUADEC proposal or on IRC.  And it's
> > another thing I'd love to be working on.  But it's a Big Task.
> > 
> > My concern in all of this is keeping our document in a good structured
> > format we can actually use.  Twiki might get you some benefits in the
> > short term, but it's a death sentence for your data.  (This is, mind
> > you, coming from the person who makes a living writing tools for other
> > formats that are also a death sentence for your data.)
> > 
> > Lots more to say on the subject, if anybody wants to hear it.  Should we
> > take this public?
> 
> Sure, go for it. I just sent it to you guys on the principle that being
> insane in public is not always healthy. ;) [And I do have responses to
> some of your points above, I think, but I guess I should subscribe to
> the docs list for that :) Can you cc: me on the post to docs-list?
> 
> Luis