Habari User Manual
khaled Abou Alfa
The advantages of using Tiddlywiki
1. It's one file that contains everything. If we want to include images these can be within one folder that is attached and that's it. Alternatively the images can be links to area online. It all depends how far we want to take this. Ultimately however it is a single file that stores everything.
2. The documentation team can have ownership of this portion of the final product. This is probably one of the reasons why documentation gets forgotten in most cases, the lack of ownership. In this case it's an integral and a separate part of the project. Integral, in that it'll be used extensively, separate in that it can be released on a different schedule to Habari. The manual could then have it's own numbering system etc.
3. We can style this so it's completely integral to our design philosophy etc. We're not beholden to anything here.
The disadvantages (which I believe we have a solution for)
1. Transfering information from the wiki to the tiddlywiki format. There is a slight difference between the two, however I'm informed (Randy?) that we can do this pretty easily. Just writing a bit of code-fu and we should be good to go.
Khaled
Owen Winkler
using the TiddlyWiki for distributed documentation. The sample that
was floating around was pretty neat. Are there any licensing issues
with deploying TiddlyWiki as documentation? Would we be ok to use a
GPL (I don't know that that's the license) TiddlyWiki for
documentation if the project is ASL? Curious.
Owen
chrisjdavis
I am +1
Chris
Michael Bishop
neglected to pick up the steam he's intended to build in that area, I
do have one question.
Is the idea still for the Media Wiki site to be a "wild west" of
documentation, user notes, etc, and then cull a final documentation
and distribute that via the TiddlyWIki? What advantage would there be
in using two different wiki formats? Why not just use Tiddlywiki for
both and just scale down the distributed version? It seems it would
be far easier to convert the existing Media Wiki pages to TW now, and
then go forward, vs continually converting the two markups, unless
there's some script out there that's automating that, then, I suppose,
my point is moot.
~miklb
On Jul 26, 10:12 am, "Owen Winkler" <epit...@gmail.com> wrote:
chrisjdavis
take the lead in this. If you would like to just use Tiddly, then I
think we should go with that.
Chris
broke...@gmail.com
------------------
-----Original Message-----
From: chrisjdavis <chris...@gmail.com>
Date: Thu, 26 Jul 2007 18:46:35
To:habari-dev <habar...@googlegroups.com>
Subject: [habari-dev] Re: Habari User Manual
Owen Winkler
> I agree with Michael it would seem much easier to just use tiddly wiki for now and keep building on that as it is the final product and the good thing is that we can get an initial release pretty soon
>
The only issue I see with this is that TiddlyWiki is not a server-side
wiki by default. I seem to remember a script that might enable that,
but we'd need to look into it. It's not going to be as simple as
throwing the TiddlyWiki software on the wiki site and going.
Owen
Tony Stevenson
Exucse my ignorance, and lack of mail history (or memory for that
matter). Why is TiddlyWiki the one of choice here?
What is the end aim for the wiki? A permanent resource for material, or
a staging ground to a more permanent set of docs etc?
I will refrain from suggesting alternates until I hear back, but surely
there are simple choices out there?
Cheers,
Tony
broke...@gmail.com
This is the place to list those alternatives however one of the reasons for choosing tiddlywiki is because it allows us to include the manual with the download and that it can be modified like a wiki. Also tiddlywiki has become pretty mature over the last couple of iterations . The thing is if you have an alternative that works better fire away at least then we will have considered the alternatives
Owen maybe the route forward is to discuss the alternatives first and then see what we can do from there in terms of server integration
------------------
-----Original Message-----
From: Tony Stevenson <to...@pc-tony.com>
Date: Fri, 27 Jul 2007 12:55:33
To:habar...@googlegroups.com
Scott Merrill
> Exucse my ignorance, and lack of mail history (or memory for that
> matter). Why is TiddlyWiki the one of choice here?
The aim is to provide a user manual shipped with the core Habari
download. For a variety of reasons, we feel a wiki would be a good
format for the end user documentation.
It's also a goal of ours to ensure that the user manual be readable even
if your site is not fully functional. Either static HTML, or some
self-contained mechanism independent of Habari is necessary to satisfy
this goal.
> What is the end aim for the wiki? A permanent resource for material, or
> a staging ground to a more permanent set of docs etc?
The goal is to use a single wiki to develop the end user documentation,
and then ship that wiki with Habari. TiddlyWiki, as a self-contained
single-page wiki with no server-side requirements, appears to be a great
choice: it's low overhead, small, and easy to use. We can quite easily
write the user manual in TiddlyWiki and then simply bundle that with
Habari's download.
The question here is how to move forward. Do we keep the MediaWiki
installation as a "sandbox" type environment, in which any interested
person can put forward suggestions, etc? If so, someone needs to move
content from MediaWiki to TiddlyWiki. Or do we just use TiddlyWiki for
all our wiki needs? Each option brings with it some challenges.
--
GPG 9CFA4B35 | ski...@skippy.net | http://skippy.net/
chrisjdavis
now that he has heard some of our reasons for choosing Tiddlywiki.
Tony Stevenson
> I would still like to hear what Tony has in mind as to alternatives
> now that he has heard some of our reasons for choosing Tiddlywiki.
>
Chris, after reading Scott's ideas for a flat file based wiki that can
be shipped with the product, I doubt I have any alternatives that will
meet that criteria.
However, do we (and I use that term loosely :-) really want to ship docs
in a format that can be easily edited (and as such possibly crawled) and
used by people non-the-wiser, taking them at face value.
Yes, I am of course well aware this could be done with most any format,
just something that popped into my tired little head.
Cheers,
Tony
Michael Bishop
what's editable by the public, that is, simply cull a meat and
potatoes version that is accurate.
I'll look at some of the server-side solutions for tiddlywiki over the
weekend, and share the experience, particularly on how easy it might
be to pull that from the server-side and include in a stand alone
version.
~miklb
> smime.p7s
> 4KDownload
Owen Winkler
>
> I think the idea is to ship a different version of the wiki than
> what's editable by the public, that is, simply cull a meat and
> potatoes version that is accurate.
Yes. The intention is to maintain separate wikis - one that would be
committed in the code for the purpose of distributing documentation.
The other would be publicly editable and contain "user documentation"
(answering questions like "How do I do X with Habari on Dreamhost?" or
"Best plugins for Y?" which aren't appropriate for the distributed
manual) as well as be a place to incubate new documentation for
inclusion in the manual.
There would be no button to push to move the online wiki directly into
the distribution, but there should be an easy enough way to move
things from one to the other as required. This is the technical
challenge.
> I'll look at some of the server-side solutions for tiddlywiki over the
> weekend, and share the experience, particularly on how easy it might
> be to pull that from the server-side and include in a stand alone
> version.
This information will be valuable.
Owen
Michael Bishop
On Jul 28, 11:11 pm, "Owen Winkler" <epit...@gmail.com> wrote:
> On 7/27/07, Michael Bishop <bishopblogwo...@gmail.com> wrote:
> > I'll look at some of the server-side solutions for tiddlywiki over the
> > weekend, and share the experience, particularly on how easy it might
> > be to pull that from the server-side and include in a stand alone
> > version.
>
> This information will be valuable.
There are several options out there, and I only tested one, but after
reading one of the developers thoughts, he uses MediaWiki for a
larger, collaborative wiki, TiddlyWiki isn't really intended for such.
Thus, I do not think this is a direction worth investigating. Reading
the discussions in their Google Groups, there is a movement for better
ability to import from MediaWiki. There is currently a plugin for
import, http://www.martinswiki.com/#MediaWikiAdaptorPlugin ,however on
brief testing, I was unable to import from Habari's wiki. I don't
know if it's a versioning issue, server config, or what. I was
somewhat able to import from Wikipedia however, so there's hope for
down the road of this being a simple process.
Martin also has a MediaWiki Formatter plugin,
http://martinswiki.com/prereleases.html#MediaWikiFormatterPlugin
,which allows you to tag a tiddler with MediaWikiFormat and it will
display the tiddler within TiddlyWiki in MediaWiki format. If that
makes sense. The only thing I'm concerned about with these plugins
are the licensing, they are a CC share alike.
http://bloggingmeta.com/doc/Habari_Manual.html you can see the
Installation ( http://bloggingmeta.com/doc/Habari_Manual.html#Installation
) tiddler was taken directly from the Wiki source.
Tiddlywiki has been upgraded I think since kahled created the original
file, feel free to save the doc from my site (I couldn't seem to
attach a file via GG), this one has the plugin "installed". Also, I
can't guarantee how long this will be up ( a few weeks at least).
All in all, I think this is a good solution, and am certainly
volunteering to do the manual copy/paste to create the shippable doc
if that's the final decision, as well as follow TiddlyWiki development
to better be able to automate the creation and updating of the
shippable docs.
~miklb
Michael Bishop
plugin author of the MW Formatter plugin (so the first shipment will
have to styled with TW code, not MW, as soon as that's resolved I'll
update and streamline the process).
In the meantime, working on the upgrade documentation, I've found the
only sticking point is that the rewrite_rules sql has to be re-run. I
suggested that we include the basic sql with the second release.
This is the file I used to upgrade the test install of the first
developer release.
http://bloggingmeta.com/doc/upgrade.sql
This is using the default table prefix, the docs will outline what to
change if that was not the case on install.
I'll post the updated docs in a bit.
~miklb
Michael Bishop
most recent incarnation. There are certainly additional plugins that
can be employed to make this less "wiki" however still sorting out the
license issues, so in the meantime, it's been updated with an upgrade
page,and all formatting is TW formatting, not using the MediaWiki
formatter.
I was able to download the page doing a save as, however upon opening,
I got a message saying it wasn't properly saved. I can provide the
actual file I have locally if that doesn't work for inclusion.
Certainly the language is open for modification, I will never claim to
be a document writer :-)
~miklb
On Aug 3, 2:33 pm, Michael Bishop <bishopblogwo...@gmail.com> wrote:
> Working on the TW doc, I still haven't gotten clearance from the
> plugin author of the MW Formatter plugin (so the first shipment will
> have to styled with TW code, not MW, as soon as that's resolved I'll
> update and streamline the process).
>
> In the meantime, working on the upgrade documentation, I've found the
> only sticking point is that the rewrite_rules sql has to be re-run. I
> suggested that we include the basic sql with the second release.
> This is the file I used to upgrade the test install of the first
> developer release.http://bloggingmeta.com/doc/upgrade.sql
broke...@gmail.com
------------------
-----Original Message-----
From: Michael Bishop <bishopb...@gmail.com>
Date: Fri, 03 Aug 2007 21:08:19
Michael Bishop
receptive to granting an individual license, and is very interested
to" understand the incompatibilities in the licenses and resolve
them, since this issue will probably come up again in future". So if
anyone can give me more information to pass onto him, that would be
great. I've also contacted the development community of TW in general
regarding this.
Feel free to email me directly the information, or post back in the
thread for posterity.
~miklb
On Aug 4, 3:05 am, brokenk...@gmail.com wrote:
> Nice work Michael hopefully we can get the license stuff for the plugins sorted out in the near future
>
> ------------------
>
> -----Original Message-----
> From: Michael Bishop <bishopblogwo...@gmail.com>
>
> Date: Fri, 03 Aug 2007 21:08:19
> To:habari-dev <habar...@googlegroups.com>
> Subject: [habari-dev] Re: Habari User Manual
>
> Alrighty then,http://bloggingmeta.com/doc/Habari_Manual.htmlis the
Tony Stevenson
> I've just heard back from the author in question, and he's quite
> receptive to granting an individual license, and is very interested
> to" understand the incompatibilities in the licenses and resolve
> them, since this issue will probably come up again in future". So if
> anyone can give me more information to pass onto him, that would be
> great. I've also contacted the development community of TW in general
> regarding this.
>
> Feel free to email me directly the information, or post back in the
> thread for posterity.
>
> ~miklb
>
Apologies for my delay in getting back to you all. Sadly my $$work has
rather taken over of late, and planning my impending wedding seems to
sap all the remaining waking moments I have.
I would truly love to get involved with this aspect of the project, but
I would not want to commit to something like this, as I could not
guarantee I would have the amount of time I would like to devote myself
to this.
I will however have much more time on my hands in late September. Alas
I would imagine that this would have been long finished by then. If not
I will pick it up more than ready to go.
Cheers,
Tony
Owen Winkler
>
> I will however have much more time on my hands in late September. Alas
> I would imagine that this would have been long finished by then. If not
> I will pick it up more than ready to go.
Work on this project should be ongoing, and I don't expect everything
to be done or completely documented by then, so please do stop by
after your wedding. ;)
Owen
Michael Bishop
formatter and importer has agreed to grant Habari Project a compatible
license to use his work in our documents. He simply needs to know
what formally needs to be done to do this. If anyone with more info
on this aspect can direct me to the appropriate form or info on how to
do this, I will get the info and then begin converting the TW to use
the MW plugin. There are a couple of other plugins I would like to
investigate in a similar fashion, to better present the TW doc as a
document, and less wiki-ish for the end user. However, this plugin
will make it much easier to migrate more of the existing documentation
to the shippable docs, as well as allow doc writers to add to the
media wiki site, and I simply cull that into the docs.
~miklb
And Tony, certainly this is going to be an ongoing process, so enjoy
your wedding, and keep an eye out for documentation development.
Owen Winkler
>
> Martin Budder, the plugin developer who has done the work on the MW
> formatter and importer has agreed to grant Habari Project a compatible
> license to use his work in our documents. He simply needs to know
> what formally needs to be done to do this. If anyone with more info
> on this aspect can direct me to the appropriate form or info on how to
> do this, I will get the info and then begin converting the TW to use
> the MW plugin.
It should be as simple as selecting the license and following the
license's instructions. TiddlyWiki plugins have a place in their info
that allow you to specify a license. Picking one and linking to it
should be sufficient, and in the case of the CC license already in
place on that plugin, it should simply be a matter of replacing the CC
license with a BSD, MIT, or ASL and a link, depending on how the
author chooses to license it.
Owen
khaled Abou Alfa
Michael Bishop
just substitute the license? We do not need any formal written
agreement?
Forgive the many questions, just want to make sure i's are dotted, t's
are crossed.
~miklb
On Aug 7, 5:33 pm, "Owen Winkler" <epit...@gmail.com> wrote:
Owen Winkler
> just substitute the license? We do not need any formal written
> agreement?
>
> Forgive the many questions, just want to make sure i's are dotted, t's
> are crossed.
I am not a lawyer.
No, there is no formal agreement. As with any creation, the author
retains the copyright to the work. He can grant what rights he has to
whomever he chooses under what conditions law allows. By providing a
license with the distribution (and indicating that it applies to the
work), the copyright owner grants the rights within the license
without the licensee having to specifically ask permission. This is
part of the point - not having to ask permission to use the work
within the bounds that the author is ok with. If he was going to
grant us a specific alternate license, that would be different.
There is no requirement to "register" the use of the license unless
maybe the chosen license requires it, but I don't know of any common
licenses that do that. We didn't register Habari's use of ASL (as far
as I know, anyway), for example.
Note also that it's ASL, not APL. ASL is for Apache Software License,
even if it's commonly confused with American Sign Language. APL is
the stock ticker for some natural gas processing company.
Owen
Michael Bishop
mole hill, I simply have been overwhelmed reading all the information
regarding this. Most of the info at the Apache site concerns the
actual ASF, and not other projects licensed under the ASL (thanks for
the correction). The reason I asked about the formalities, is I did
see http://www.apache.org/licenses/software-grant.txt, which I didn't
know if it pertained to other projects using their license.
I guess I can consider this resolved, the other plugins I looked at do
not really contribute anything meaningful to the documentation
presentation, so until something crosses my path, I think this portion
of the process is resolved.
I suppose my eagerness to participate in a more meaningful way has
been a bit aggressive, I just didn't want to inadvertently create an
issue down the road.
~miklb
On Aug 7, 8:31 pm, "Owen Winkler" <epit...@gmail.com> wrote: