[Xapian-discuss] xapian wiki

[Peter Masiar]

Olly Betts wrote:
> On Thu, Mar 16, 2006 at 10:06:46PM -0500, Peter Masiar wrote:
>> One option would be to have "most current" docs as wiki only.
> 
> I'm not sure I want to make a net connection a requirement for updating
> documentation though.

You don't have to require wiki updates. It is just yet another, quick 
way to keep docs up-to-date. On page footer just add something like:

  "Suggestions to this page? It's a wiki so you can edit it yourself,
  or if you prefer email, sent suggestions by emails to olly at ..."

As I mentioned before about 10% of wiki readers ever edit pages, so we 
are talking about possible 3-5 people editing wiki directly.
So it's you, me, maybe Philip Neustrom and maybe someone else. :-)

IMHO it is about "instant gratification". If I need to write docs in 
some special format and submit is as patch, then hope that my patch will 
be applied by somebody - it is a long wait to see results. But if I can 
go and change docs, I can help someone immediately, and it is easier to do.

I have yet to learn how to create patch. :-(

My experience might be "tainted" by the fact that my first open source 
project I got involved with was a wiki, and all discussions were in 
wiki. Email list was used only to get (daily) notification which pages 
changed.

Another "gentle prodding" trick might be to add link to wiki to email 
list footer (or to your sig), with suggestion:
"If we answered your question, please contribute back to docs: update 
appropriate wiki page".

It might be hard to do it now (not much info in wiki), but if some gurus 
start responding to email questions by updating relevant wiki page and 
posting the link, it will grow in time.

Yes, it is hard to change perceptions. People are used that HTML pages 
are static (and often obsolete), cannot be changed easily.

> 
> But I think the key thing is to make the wiki markup the master
> format and to be able to convert it into HTML of similar quality to
> that we currently have so we can ship it with the downloads.
> 
> We just need a scriptable way to do the conversion.  Probably best is
> to run it through the moin rendering code with a suitable style.

As I said my favorite wiki now is TRAC. I will look into how to generate 
such HTML hardcopy of wiki pages from TRAC. I guess exercise in wget. :-)


-- 
Peter Masiar

A: Because it messes up the flow of reading.
Q: Why is top-posting often frowned upon?