[BitPim-devel] wiki documentation

[Mark Weber]

I have had a look at the experimental
BitPim wiki, www.bitpim.org/wiki

I've got some questions about the wiki, to try to
understand it's intent:

o) Is it just experimental, or is it under development
with intent to go live?

o) Is the intent to replace the current local documentation
(and web site documentation) with the wiki?

o) Any intent to keep the local help?

o) What about openness versus security? Is there
an agreed upon strategy?

IMO, the wiki would be a great forum for the documentation,
especially the "Phones" section. It seems to me that
"Phones" section is the primary area that would benefit
by wider authorship.

__________________

My suggestions:

o) first, migrate the "supported phones" to the
wiki, and see how it goes

o) after the wiki goes live for the supported phones,
remove this section from the user manual, to
reduce doc maintenance as well as to encourage
users to read/update the wiki. Change the local
documentation to link to the wiki.

o) vandalism: require login for updates;
no second chances for vandals.

__________________

I'm willing to help do this.
What's next?

[Joe Pham]

o) Is it just experimental, or is it under development with intent
to go live?

With intent to go live. Stephen cam up with what we have right now,
but he hasn't had time to complete it. I was planning to go back to
it after release 1.0.0

o) Is the intent to replace the current local documentation (and web
site documentation) with the wiki?

Possibly, based on how well the wiki is turning out.

o) Any intent to keep the local help?

Not if it's redundant.

o) What about openness versus security? Is there an agreed upon
strategy?

I don't think we have a strategy per se. It's supposed to be a
community thing, so I'd leave it to the community to decide.

o) first, migrate the "supported phones" to the wiki, and see how it
goes

Not sure what you meant by this. Are your referring to the Phone
Help pages?

o) after the wiki goes live for the supported phones, remove this
section from the user manual, to reduce doc maintenance as well as
to encourage users to read/update the wiki. Change the local
documentation to link to the wiki.

I'd still prefer to maintain the (offline) User Doc, so we need to
figure out an efficient way of transferring data back and forth.

o) vandalism: require login for updates; no second chances for
vandals.

Curious as to how the other wiki sites handle this?

-Joe Pham

[Mark Weber]

Post by Joe Pham

Post by Mark Weber
o) Any intent to keep the local help?

Not if it's redundant.

(see below)

Post by Joe Pham

Post by Mark Weber
o) What about openness versus security? Is there an agreed upon
strategy?

I don't think we have a strategy per se. It's supposed to be a
community thing, so I'd leave it to the community to decide.

(see below)

Post by Joe Pham

Post by Mark Weber
o) first, migrate the "supported phones" to the wiki, and see how it
goes

Not sure what you meant by this. Are your referring to the Phone
Help pages?

Yes, what I meant to say was the hierarchy below "phones" folder
in current documentation.

Post by Joe Pham

Post by Mark Weber
o) after the wiki goes live for the supported phones, remove this
section from the user manual, to reduce doc maintenance as well as
to encourage users to read/update the wiki. Change the local
documentation to link to the wiki.

I'd still prefer to maintain the (offline) User Doc, so we need to
figure out an efficient way of transferring data back and forth.

hmmm ... this seems to be at odds with what you said above,
"Not if it is redundant". In any event, seems that everyone would
agree:
a) there is strong benefit to having doc available locally
b) there is some effort required to migrate from wiki to local doc

If (b) can be kept small, its probably worth the trouble.

Post by Joe Pham

Post by Mark Weber
o) vandalism: require login for updates; no second chances for
vandals.

Curious as to how the other wiki sites handle this?

Wikipedia has a variety of responses to vandalism, depending
on circumstances.

o) strongly favor openness to get people started and comfortable;
no login required for most edits

o) monitor recent changes, reverting (and scolding) when changes
are inappropriate

o) repeat offenders are banned

o) some common targets to vandalism are locked from
anonymous editing; in more extreme cases, some articles
are locked from all edits

I don't know how other wiki's besides wikipedia handle it;
probably a variety of strategies and a variety of success.

======================

An approach to launch the wiki that I think would be
workable is as follows:

a) Use an incremental approach ... if for any reason the
wiki is not workable, it's better to find out with less work
than with more. Plus, gets going earlier rather than later.
I suggest using the "phones" help section as guinea pig.

The switchover to wiki could be phased: First release could
have stale "phones" help; later release could drop it
completely (or, if worth the trouble, convert wiki
to local help)

b) For security of information, require login to wiki, but
grant access pretty much automatically. I think this will
deter the casual vandals; deterring a determined vandal
is harder, but hopefully won't be much of an issue.

Note that getting started would require almost no change
to current BitPim: Just a link somewhere near front

Post by Joe Pham
For perhaps more current information on your phone,
have a look at our wiki: www.bitpim.org/wiki

Even if the the first launch was incomplete on the
"phones" hierarchy, it could turn out to be quite useful
and would be a start, regardless.

Other approaches would work too ...

I'm not particularly concerned about the details, but I
would like to see a wiki used for the documentation,
and I'm willing to help get it going.

[Stephen Wood]

Post by Mark Weber

Post by Joe Pham

Post by Mark Weber
o) Any intent to keep the local help?

Not if it's redundant.

(see below)
...

[Stephen Wood]

Mark, devel list:

I am the one who set up the Wiki originally. If you would like, I can give
you the Sysop password. If you need to make changes the require changes to
Wiki config file, let me know and I'll do them.

My thougth on security was to require a login, with accounts setup on
request. But I don't have strong opinions. If account setup is not done
through a moderator, then running some script to cleanup spam would be
needed.

In the absence of totally switching over to the Wiki, I was hoping that the
Wiki could be used as a place for users to put FAQ's, details on seting up
the development version, and tip and tricks for specific phones. Much of
this should end up in the documentation, but the Wiki lets users publicize
useful information without the turnound time of getting the attention of a
developer and getting it added to the next release, which could take time.

I would like to work on the Wiki, but if I am realistic, I won't. I have
busy summer coming up.

At some point I copied some of the web pages into the Wiki. Since they are
now out of date, they should probably be replaced with a page with pointers
to the BitPim web pages and an explanation of what the current role of the
Wiki is.

I would like to work on scripts to transfer help back and forth from the
Wiki. But I'll work on it only if you don't think yourself or someone else
could work on it in the next month.

Stephen

Post by Mark Weber

Post by Joe Pham

Post by Mark Weber
o) Any intent to keep the local help?

Not if it's redundant.

(see below)
...

[Mark Weber]

Totally cool. I think we are in substantial agreement
with the overall scope of this.

Yes, I'm willing to work on it in the next month. I would
suggest that we start small and get something
completed earlier, rather than starting bigger with
later completion. I'll be able to put in a few hours
a week, perhaps up to 10hrs/week or so.

I thinking the next step would be to decide the general
intent and direction. Here are my thoughts; other
suggestions welcome:

1) The intent is to use the wiki as the source. The wiki
would first be loaded up from the help doc, but this would
be a one-time only thing. After any particular section was
loaded into the wiki, the wiki would become the source
for that section. Edits would be in the wiki, and the help
would be generated from there.

2) wiki to require login; accounts set up on request

Any other suggestions? Any objections?
Do we call a vote or what?

====================

Early action items:

a) get consensus on overall direction
b) decide what section to do first
c) put a link in the existing help, pointing to the wiki
d) write scripts to transfer to/from wiki
e) require login to wiki
f) write intro for wiki


Stephen,
If you want to work on scripts to transfer to and from,
that would be great. I can write the intro and page through
the wiki after it is loaded, polishing up as appropriate.

I know nothing about admin side of MediaWiki, so I'm
happy to leave that to others.

Some admin details:
I tried to use the table of contents feature built in to
MediaWiki, but I was unable to do so. Perhaps this
is disabled in the config? It's always possible I'm
doing it wrong, but it seems so easy that I'm thinking
it's a setup issue.

My suggestion on where to start is the "phones"
folder, mainly because this is the section that would
benefit the most by updates from the user community.

We should probably use templates in MediaWiki.
I don't know how to set them up, and I'm not sure if
this is an admin function or not. Do you know?
If not, I can research it.

Post by Stephen Wood
I am the one who set up the Wiki originally. If you would like, I can give
you the Sysop password. If you need to make changes the require changes to
Wiki config file, let me know and I'll do them.

[Stephen Wood]

Post by Mark Weber
...
d) write scripts to transfer to/from wiki

I will start working on this.

e) require login to wiki


Anonymous editing of the wiking has been disabled.

Post by Mark Weber
I tried to use the table of contents feature built in to
MediaWiki, but I was unable to do so. Perhaps this
is disabled in the config? It's always possible I'm
doing it wrong, but it seems so easy that I'm thinking
it's a setup issue.

Not sure how to get a table of contents. But
http://bitpim.org/wiki/Special:Mostrevisions shows the pages with the most
revisions, and as there are only 4, it shows them all. The only page with
unique content is "SupportYourPhone" which another user has written. The
other pages, are out of date. The "BitPim" should be replaced with an
explanation of the Wiki and links to the BitPim web. If Joe agress, the
"Developer Information" and "Todo" pages should be updated to reflect the
current web pages and then those pages get replaced with redirects to the
Wiki.

...

Post by Mark Weber
We should probably use templates in MediaWiki.
I don't know how to set them up, and I'm not sure if
this is an admin function or not. Do you know?
If not, I can research it.

I don't know what templates are. Post what you know/find about their
utility.


Stephen

[Joe Pham]

Post by Mark Weber

Post by Joe Pham
I'd still prefer to maintain the (offline) User Doc, so we need to
figure out an efficient way of transferring data back and forth.

hmmm ... this seems to be at odds with what you said above,

I mispoke. I meant redundant between the wiki and the online Help
pages (not the local Help as part of the BitPim program). As
previously stated, I'd prefer to maintain the local Help pages, and
it could be as simple as taking a wikik snapshot to build the Help
pages for each BitPim release.

I'm also Ok with your other suggestions.

-Joe Pham

[Joe Pham]

Post by Mark Weber
a) get consensus on overall direction

+1 from me.

Post by Mark Weber
b) decide what section to do first

A user has already started on the How To Add Phone Support section.
I'm also OK with Phone Help pages.

Post by Mark Weber
c) put a link in the existing help, pointing to the wiki

During the initial transition period, we may have to maintain both
links.

Post by Mark Weber
d) write scripts to transfer to/from wiki

Mainly for building the local Help off the wiki pages. Tranferring
to wiki is a one-time deal.

-Joe Pham

[Christopher Matuszak]

well i have an idea but it would take about a week or so to implement.

I could make a script from within the wiki admin section to export the current wiki docs(selectable sections etc) to a compiled html help file..... to do so though would take a considerable chunk of time on my part....

but an idea is an idea...and it is a very good one in the fact that it helps to break the process of transferring to one step!

[Joe Pham]

If Joe agress, the "Developer Information" and "Todo" pages should
be updated to reflect the current web pages and then those pages get
replaced with redirects to the Wiki.

Sounds good to me!

-Joe Pham

[Mark Weber]

All good.

I'll be working in the wiki soon, writing an introduction
and documenting our strategy, so that people not on
this list can read it. Also, we'll be able to adjust the
strategy there as needed.

Just so you know, most of my available time
will be weekends.

Chris,
Just a suggestion ... there may already be software for
converting MediaWiki to compiled html. May save some
time (or not, depending on what's there).

Post by Joe Pham

If Joe agress, the "Developer Information" and "Todo" pages should
be updated to reflect the current web pages and then those pages get
replaced with redirects to the Wiki.

Sounds good to me!