Re: BitPim Wiki approach

On 7/22/07, Joe Pham <[email protected]> wrote:
> I finally got a chance to look at the Wiki stuff.  My observations
> are as follows:
>
> 1. I don't see any good automatic way of transferring contents from
> Wiki to Helpblocks (BitPim help source format).  I'm open to any
> suggestions as how to better do this.

It's unfortunate,  but I think that's where we are. If a solution presents
itself in the future, we can always use it then.

> 2. Tranferring contents between BitPim Help to Wiki can be done
> fairly easily, though I see this as a one time deal only.

Agreed.

> My suggestions:
>
> 1. Somehow functionally organize the Wiki contents into 2 parts:
> a "Read Only" part exported from the current BitPim Help, and
> an "editable" Wiki part contributed by users.  From inside the BitPim
> Help, I'll add a link to the Wiki part(s).  Pertinent changes to the
> Help suggested from users will be manually updated.

Earlier, I was thinking the "editable" stuff would be just the phones
section. Stephen suggested adding the FAQ and the linux issues,
which sounds like a good idea to me. Anything else?

> 2. For each BitPim release, the Help will be exported to the Wiki
> pages.

We could do this, but consider Wikispaces does not support
a bulk import, so this a manual copy/paste operation for each
page.

Perhaps we should just split out the editable stuff and have
it live in the wiki only, without re-export every release. The wiki
would have the high-maintenance stuff, not the nuts-and-bolts
of how to use BitPim.

This would mean there would really be two completely separate
docs, with no overlap.  BitPim help would continue to use
Helpblocks, which would be independent of the wiki.

Additionally, for those users who for whatever reason don't have
a web connection that is reasonable to browse with, we could
export the HTML from the wiki, and include that with the BitPim
release, as raw HTML. This is very easy in Wikispaces and would
enable users to download BitPim plus the wiki docs, and browse
even when not online.

> 3. Organize the contents of each phone into 1 Wiki page or file so
> that it can easily be linked.

This is what I had been doing for the first several phones, but
then I realized that many of the phones have quite long documents.
So I saw the wisdom of the current organization: A header page,
and typically three sub-pages:  cables, notes, and howtos.

Are you thinking there will be a phone-by-phone link from
the help into the wiki?

====

Here's the current status of the wiki work:

1) Stephen recently sent me another pass at the converted
files.

2) I've completed importing the "About BitPim" section,
with all the sub-documents. Perhaps there are some broken
links, but not very many. I did this section early because
several of the phones link to it.

3) While doing (2), I've been re-filtering the files Stephen
sent me through a perl script that I've been working on,
to further automate the import. The script is nearly perfect
now, requiring almost no manual edits to get a nice
looking wiki, with style very similar to the help.

4) I've starting re-doing the phones section; I've completed
Audiovox and the first two LG phones. I expect to do a
few tonight, then more later in the week.

5) As far as the one-page-per-phone versus hierarchy-
for-each-phone, I'm now planning on preserving the current
BitPim hierarchy. If we want to reorganize later, that's
easy to do entirely within the wiki.


Joe,
If you're in more-or-less agreement with the above,
I'll update the "wiki strategy" document for your review.
We can then proceed from there.

Regardless, while this conversation is going on,
I'll be plugging away at populating the wiki. If any
wikified stuff gets pitched because it belongs in the
help and not in the wiki, so be it.

Regards,
Mark.

-------------------------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc.
Still grepping through log files to find problems?  Stop.
Now Search log events and configuration files using AJAX and a browser.
Download your FREE copy of Splunk now >>  http://get.splunk.com/