wiki as help

[duck-3]

As I remember, time ago we discussed the feature of our “help”  
mechanism. Some purposed to drop the help.xml files (are really  
outdated) and to use wiki. But Jan objected, because as we cannot use  
it off-line.

I am now in front of a occasion that I must maintain two wiki  
installations with nearly the same content  and of course I wont to  
have one help menu option – the wiki.

As first I am going to add a sync feature to wiki pages. It will
1.Download new pages from remote wiki installation
2.Upload new page from local to remote wiki
3.Show difference between local and remote pages, check both history  
to auto-detect and purpose to download or upload content (this if a  
page was changed only on one side)
4.Display difference between pages if automatic mechanism fails (if  
the pages has no history match or better said was changed on both sides)

Of course this can be used to sync offline installations. So we can  
drop the help.xml. Or we can create a new renderer to prepare help  
files from wiki pages and distribute them with the releases. Even I  
think that is better to link help to wiki.horde.org, this should bring  
more documentation contributions.

Any Ideas?

Duck

--
Horde developers mailing list - Join the hunt: http://horde.org/bounties/
Frequently Asked Questions: http://horde.org/faq/
To unsubscribe, mail: dev-unsubscribe@...

[Eric Jon Rostetter]

Quoting duck@...:

> As I remember, time ago we discussed the feature of our “help”  
> mechanism. Some purposed to drop the help.xml files (are really  
> outdated) and to use wiki. But Jan objected, because as we cannot  
> use it off-line.

I agree with Jan, but...

> Of course this can be used to sync offline installations. So we can  
> drop the help.xml. Or we can create a new renderer to prepare help  
> files from wiki pages and distribute them with the releases. Even I  
> think that is better to link help to wiki.horde.org, this should  
> bring more documentation contributions.

We could create a wiki to maintain the help pages, and a process as
described to convert the wiki pages to the help.xml files for the
distributions.  In the resulting help.xml files can be a link to
the wiki 'for more current/up-to-date help information see ...' or
some such...

> Any Ideas?

I'm not against keeping the system we have now.  In fact, it has some
advantages (local customizations are easier, etc).  But if we did as
above (a wiki, which is extracted to be included in the release), then
this might be the best of both worlds.

I know of several projects that do a wiki, and then tar-ball the wiki
as html or text into each distribution.  So this would be just an extension
of that idea (help files instead of tar balls).  We'd just need an
automated process to convert the wiki into help.xml files...

> Duck

--
Eric Rostetter
The Department of Physics
The University of Texas at Austin

This message is provided "AS IS" without warranty of any kind,
either expressed or implied.  Use this message at your own risk.

--
Horde developers mailing list - Join the hunt: http://horde.org/bounties/
Frequently Asked Questions: http://horde.org/faq/
To unsubscribe, mail: dev-unsubscribe@...

[duck-3]

Quoting Eric Jon Rostetter <eric.rostetter@...>:

> Quoting duck@...:
>
>> As I remember, time ago we discussed the feature of our “help”  
>> mechanism. Some purposed to drop the help.xml files (are really  
>> outdated) and to use wiki. But Jan objected, because as we cannot  
>> use it off-line.
>
> I agree with Jan, but...
>
>> Of course this can be used to sync offline installations. So we can  
>> drop the help.xml. Or we can create a new renderer to prepare help  
>> files from wiki pages and distribute them with the releases. Even I  
>> think that is better to link help to wiki.horde.org, this should  
>> bring more documentation contributions.
>
> We could create a wiki to maintain the help pages, and a process as
> described to convert the wiki pages to the help.xml files for the
> distributions.  In the resulting help.xml files can be a link to
> the wiki 'for more current/up-to-date help information see ...' or
> some such...
>
>> Any Ideas?
>
> I'm not against keeping the system we have now.  In fact, it has some
> advantages (local customizations are easier, etc).  But if we did as
> above (a wiki, which is extracted to be included in the release), then
> this might be the best of both worlds.
>
> I know of several projects that do a wiki, and then tar-ball the wiki
> as html or text into each distribution.  So this would be just an extension
> of that idea (help files instead of tar balls).  We'd just need an
> automated process to convert the wiki into help.xml files...

I did a basic render and used Turba's help.xml as an example:  
http://bugs.horde.org/ticket/7154. With it, we can manage the help  
content online and update help files in the release process. We can  
even distribute
help as html or text format someone would like to. But I will like to  
see an configuration option to use a local help file or to link to a  
desired wiki.

Duck

--
Horde developers mailing list - Join the hunt: http://horde.org/bounties/
Frequently Asked Questions: http://horde.org/faq/
To unsubscribe, mail: dev-unsubscribe@...

[Chuck Hagenbuch]

Quoting duck@...:

> I did a basic render and used Turba's help.xml as an example:  
> http://bugs.horde.org/ticket/7154. With it, we can manage the help  
> content online and update help files in the release process. We can  
> even distribute
> help as html or text format someone would like to. But I will like  
> to see an configuration option to use a local help file or to link  
> to a desired wiki.

This seems like a better direction to go than the help.xml files; I  
think bundling a static HTML version of the help with the app makes  
sense also, since the current XML format gives us pretty much no  
benefit except for the crude searching - how would we do search with  
this?

On the other end, I guess we'd need an organizational standard for  
naming translations of the help docs, and version numbers. How do you  
suggest we deal with translations? Now at least we have the ability to  
make sure that an untranslated version of each help "item" is present.

-chuck

--
Horde developers mailing list - Join the hunt: http://horde.org/bounties/
Frequently Asked Questions: http://horde.org/faq/
To unsubscribe, mail: dev-unsubscribe@...

[duck-3]

On Thursday 07 August 2008 06:46:11 Chuck Hagenbuch wrote:

> Quoting duck@...:
> > I did a basic render and used Turba's help.xml as an example:
> > http://bugs.horde.org/ticket/7154. With it, we can manage the help
> > content online and update help files in the release process. We can
> > even distribute
> > help as html or text format someone would like to. But I will like
> > to see an configuration option to use a local help file or to link
> > to a desired wiki.
>
> This seems like a better direction to go than the help.xml files; I
> think bundling a static HTML version of the help with the app makes
> sense also, since the current XML format gives us pretty much no
> benefit except for the crude searching - how would we do search with
> this?
>
> On the other end, I guess we'd need an organizational standard for
> naming translations of the help docs, and version numbers. How do you
> suggest we deal with translations? Now at least we have the ability to
> make sure that an untranslated version of each help "item" is present.

I don't know all about naming wiki pages logic but, I purpose to create help
pages like project pages appended with some special keywords like:
/Help – ex: Project/Turba/Help – cotains current help file s content
/FAQ – ex: Project/Turba/FAQ – conatins frequntly asked questions
/Api – ex: Project/Turba/Api – conatins reflactor rendered API definitions

Than we create another special block like „[[toc]]“ named „[[langs]]“ to show
avaiable transations. It shod sccan the DB for pages called PagenameXxYx where
XxYy are a locales defined in nls.php. For example Project/Turba/HelpSlSI or
Project/Turba/HelpItIT …. If a requested locale page is not found, we should
allow a user to add create a such page and of course to show him the available
locales.
For API versions we can create subpages like /Api/Version (ex
Project/Turba/Api/32cvs) and leave the main API page (probably a special page)
to just show a list of available versions and to advertise the version is
currently installed.

Duck

--
Horde developers mailing list - Join the hunt: http://horde.org/bounties/
Frequently Asked Questions: http://horde.org/faq/
To unsubscribe, mail: dev-unsubscribe@...

[Chuck Hagenbuch]

Quoting Duck <duck@...>:

> I don't know all about naming wiki pages logic but, I purpose to create help
> pages like project pages appended with some special keywords like:
> /Help ? ex: Project/Turba/Help ? cotains current help file s content
> /FAQ ? ex: Project/Turba/FAQ ? conatins frequntly asked questions
> /Api ? ex: Project/Turba/Api ? conatins reflactor rendered API definitions

I'll respond to some of the rest of this later, but one point here -  
if we're going to make use of a wiki for help, then the help file  
shouldn't be a single wiki page. It should be a whole tree of topics.

-chuck

--
Horde developers mailing list - Join the hunt: http://horde.org/bounties/
Frequently Asked Questions: http://horde.org/faq/
To unsubscribe, mail: dev-unsubscribe@...

[duck-3]

On Saturday 30 of August 2008 06:32:57 Chuck Hagenbuch wrote:

> Quoting Duck <duck@...>:
> > I don't know all about naming wiki pages logic but, I purpose to create
> > help pages like project pages appended with some special keywords like:
> > /Help ? ex: Project/Turba/Help ? cotains current help file s content /FAQ
> > ? ex: Project/Turba/FAQ ? conatins frequntly asked questions /Api ? ex:
> > Project/Turba/Api ? conatins reflactor rendered API definitions
>
> I'll respond to some of the rest of this later, but one point here -
> if we're going to make use of a wiki for help, then the help file
> shouldn't be a single wiki page. It should be a whole tree of topics.

Of course the basic module page (like TurbaHelp) will be an basic module
introduction page with links to all related pages and resources.

Duck

--
Horde developers mailing list - Join the hunt: http://horde.org/bounties/
Frequently Asked Questions: http://horde.org/faq/
To unsubscribe, mail: dev-unsubscribe@...