I've been through the Official QM PDF docs a couple times and will
certainly be referring to them often. I came to NuWiki to see what
other tidbits of insight could be derived from the community. I'm
optimistic that NuWiki provides a good framework in which users can add
their own notes about QM and other products, but at the moment I'm
disappointed that there are now two versions of essentially the same
information, word for word in most cases, and NuWiki doesn't yet seem
to present any value-add for QM users.  (Am I being diplomatic enough
there?) It's so word-for-word in fact that I see the same errors and
lack of detail for some topics in both media.

Rather than just complain about it, I'll consider this an opportunity
to try to fix problems as I find them, but I want to make sure any
effort by myself or our colleagues isn't just a waste of time.

- I don't want to read NuWiki HTML text that's exactly the same as the
official QM PDF. How can I find a delta of what's been changed in
NuWiki?  (Loaded question, probably unanswerable but I still don't want
to waste time.)
- How often does Martin check NuWiki for updates, and what happens if
he disagrees with something found here?
- It seems the PDF has changed the organization of a couple minor
topics where NuWiki has not. It's obvious the docs are forking. Is
there any process in place to sync the docs periodically? This is of
course a natural consequence of this sort of unofficial effort but
again, I'm concerned that people will be coming to the Wiki to get
additional insight only to find the exact same content re-organized.

What can be done to improve this? It might seem strange, but
eliminating duplicate content from NuWiki might be the best way to
improve its value. Wherever the QM PDF docs have absorbed content that
has been contributed to the Wiki, remove it from the Wiki (maybe hide
it rather than deleting it for archive purposes). This way the Wiki
material will always be unique and supplemental.

I think a Wiki has real value when it provides information that can't
be found anywhere else, or if information is simply restated by a user
with the intent of clarifying something that the official docs aren't
clear about. So far this QM section of NuWiki seems to be more of an
example of NuWiki features than a sincere effort to provide value-add
to QM users. (That's no surprise and there's nothing wrong with that,
but frankly I think more people will be coming here for content than to
be sold Wiki software.) By proving itself to be a valuable resource,
NuWiki should get recognition for its own merits. If no extra value is
perceived then the Wiki software itself may not get the credit that
Binary Star is seeking.

Separate topic but related: I see one area in the QM material where I'd
like to propose a reorganization of the content, without actual change
to the text - some content seems to be mis-categorized. (Maybe this was
something that Martin fixed in his doc that no one addressed in NuWiki.
This sort of catch-up game will never end and wastes the time of anyone
who tries.) How do we go about making proposals without actually making
changes? Just write them up here in this forum?

Thanks for your time.
T

That's interesting, as the QM stuff in here is at least one release
behind the "official" version, put here as a test / demo of NuWiki in
the Summer of '06. Martin asserted that his text was corrected /
updated / enhanced in "nearly every release", hence his reluctance to
a) provide a release version on docs and b) participate in this
project.

So the "value-add" portion might be of limited value for now until
others see fit to participate.

We explained to Martin that we could offer "protected" content, in
which any changed would necessitate his approval prior to being made
public, but he chose to ignore this.

While the effort is noble, it may be futile. Despite endorsement from
such heavyweights as Doug Dumitru and a few others, Martin chose to
take the direction of pumping his previous iterations of docs through
an HTML parser, so we feel as though we at least helped bring about
on-line docs for the Linux people, who would not have been able to use
his other choice of Windows Help format.

Doug also reactivated a tired old Wiki system of his own that had had
some content from several years ago, but no QM doc content. And it
looks like one of the standard PHP ones, so there is a big disconnect
in the databases.

The history of each item is available for all to see.

Given that this is a circa May, 2006 release and QM has subsequently
released a new set  f docs, in HTML at least, if not in fact corrected,
this set is out of sync with the "official" (release version / date
unknown) version.

As an aside, I pointed out the roughly 50-60 typo-type errors I found
and fixed during the creation of this doc, to be informed by Martin
that the correct thing to do is to fire off an email for each such
correction to  his tech support address. Then it can be fixed, updated
and the entire user base can be alerted to download an entirely new set
of docs for the corrections. Sort of counterintuitive to Wiki's, huh?

The funny thing is, I conducted a test on his new stuff, dropping
entire topics in their original HTML format into NuWiki and they look
beautiful, but we have lost interest in furthering this pro-bono effort
in light of the reaction from the QM factory.

That one's easy: never. He said so himself in his forum. Even Doug was
unable to persuade him to consider the power of Wiki. So once again,
we're probably too early for this, or simply need a different approach
to convince the doc owners that they do not lose any control over their
content, and on the flip side get armies of helpers to make
it better.

I can pump the HTML version in there right now, but I won't for two
reasons. One, what's the point? Two, while his HTML plays well inside
NuWiki, his choice of using frames in his HTML is of dubious value in
this context, so it would benefit from at least converting that bit
out.

Well, Henry suggested that we use this forum as a place to "put all the
things that Martin did wrong", but we have not acted on that. A few
dedicated people have continued to add content, I monitor the traffic
and see that a surprising number of others at least look at it,
but without some occasional words of encouragement, we find it hard to
pursue what is essentially labour of love projects when  there are
paying gigs to focus on.

That could be the rough copy for our brochure. It *is* here to
demonstrate NuWiki features. I used QM as a dogfood site for that very
reason.

Others saw the value of an independent place and have participated,
contributing new content not found elsewhere. That's what it will take.

We'll continue to host it, free, of course, and no one needs to spend a
dime to use or update it.

Henry also said to me, and I quote, "This is the greatest thing ever
for Pick platforms. Everyone should be using this". There. I found a
public forum where I could state that. As usual, TG, we're too early to
the dance. Just like starting Unix classes years before Pick people
realized they would need to know it, here we are with a means of
delivering collaborative documentation and non-linear application
frameworks in a familiar Pick/MV environment, without a speck of
knowledge required about such languages as PHP, where most of the other
Wikis reside.

You could do that here, you could have at it, you could place comments
on specific topics. I basically did an "EPick" approach to his stuff,
ripping content from specific topics and tagging them accordingly. I
have to agree that the end result is weird, and I would not have
organized it that way. But I wanted the first cut to be as familiar and
comfortable as possible
to the ones whose opinions would help determine its direction.

Now that those opinions are known and shown to not give a whit about
this project, we invite any reasonable contributions to its direction,
but are not likely to be working too hard at keeping it current with
the factory.

And thanks for your contributions, Tony.

Best,

j.

Jon Sisk
Chief Editor, Nuwiki.com

Thanks Jon.

If it hasn't already happened, it's obvious that this QM section of the
NuWiki is going to fork to a point of unusability.  Your (Binary Star)
primary focus is really on selling software, not providing content for
other products.  Old and inaccurate docs on the site can only hurt your
cause.  If the bait tastes bad the fish won't bite.  If there is little or
no public support for this project then the damage has already been done
and it needs to be fixed.  I think it can.

I propose you create a new QM section which intends to replace the old
section.  The new section will start with nothing but unique contributions
from the community.  There should be no duplication of official product
docs.  If Martin sees content that he believes should be incorporated into
the product then he should have a license to do so.  When such content does
become a part of the product, it is no longer unique value-add, and it can
be edited out of the wiki by whomever finds the duplication.  (It would be
nice if Martin made a note in the wiki himself that the content is being
put into the product, as this would make it easy to find later.)  Note that
wiki content shouldn't be deleted by default.  Martin may paraphrase info
in the official docs where the community believes the wiki actually
describes the info better.  The wiki data can be edited down rather than
being removed entirely, again to just the value-add differences that make
it a worthwhile resource.

The wiki should include references to specific locations in the official
documentation where people can get more info on a given topic.  Where the
product docs don't cross-reference effectively (and I found a few such
cases) the wiki can suggest See Also categories that doc readers might
otherwise not have thought about.  This is all about value-add and
providing something that is NOT already in the docs.

A wiki doesn't need to be a comprehensive resource of all information,
which seems to have been the original intent of this QM initiative on
NuWiki.  A wiki can serve well as a repository of esoterica, hints, and
hacks, a place where the community brain dumps those little bits of insight
that might help others, a publicly hosted alternative for the personal
notes that all of us scratch out for ourselves as we learn something new.
Maybe the secret to a good wiki in this case (and a good demonstration of
the NuWiki product) is to keep the content as small as possible rather than
trying to make it into just another WikiPedia.  This also gives
editors/admins less to fuss with and keeps the project from becomming a
time consuming burden.

Any help?
T

I'll help from time to time.  Don't worry about it dieing or it being
outdated, all docs will be somewhat out of date, especially if a human
is not being paid to update them.  I think Jon is right when he says
its "Too Early."  It will take time for this "Open Source MV Community"
to grow.  We probably need more 14 year old kids who have nothing else
better to do than to code in QM BASIC and add stuff to a wiki.

It seems to me that the people with the most knowledge (who are also
the brightest folks in the MV community), are busy making money- either
so they can eat, or live the American dream.  Updating docs for free
doesn't usually make them money....

AND

These bright folks usually aren't very good teachers or documenters.
So, the documentation falls on saps like me, when we take the time to
put it together (no offense to anyone who is a good coder/bright person
and can document well too)

So if you're worried about the official docs not being updated, just
put a note on there with the latest QM release version and a date.  Its
a shame that the Ladybridge folks don't maintain or don't want to
maintain online (HTML) docs.  But it is what it is, and they have their
reasons.

So don't give up yet, I'm sure as long as NuWiki hosts the QM wiki,
people will eventually add more things, hopefully...

Maybe I am way off base, but I think that if the NuWiki project had
started off as more of a generic multivalue wiki that had branches to
more specific products, it might have garnered more interest.  While I
use QM, my knowledge base is much more R83/AP/D3 oriented and
contributions would have leaned more in that direction.  I don't know
if I am one of the bright ones, but I do know that my teaching and
documentation skills are virtually non existant.  So while my
contributions would be limited, it would be nice to have a more rounded
resource.

While I'm here, I just want to say that I think that it is awesome that
Jon is making himself accessable here.  Jon, my copy of your Pick
Pocket Guide is well worn, and still used today.  Your legacy in our
industry will be around forever.  Thank you.

First off, thanks for the kind words, Tracy. Very nice of you to say.

Second, I have a hard time referring to NuWiki in past tense, as in if
"it had had this feature, it would have..."

Third, by virtue of my following reasoning, maybe this post will
address comments and concerns of the previous three, which all had good
suggestions and content.

NuWiki started as an idea. An idea to bring a new way of visualizing
and organizing documentation. While we didn't invent Wiki per se, we
brought it to the Pick space. As an aside, this is actually not that
far from what I invented for EPick back in '91-92, where we broke down
the barriers between the code and the docs so that everyone could
participate in the process without having to go through the
documentarian in-basket dance.

Today, when I find myself explaining Wiki to people of varying degrees
of technical proficiency, I describe it as "Web pages that you can
update". That seems to click for everyone. I then proceed to explain
that our checks and balances are a bit different from Wikipedia, which
almost everyone has heard of. As such, we do not allow anonymous
updates. We feel that if someone wants to commit changes, there should
be some accountability attached. This seems to be a small price to pay,
and has a subtle effect on content, possibly preventing spurious
comments and certainly eliminating drive-by graffiti.

So here we have the previous three posters all suggesting what it could
or should be. Let me observe that each of you have the power to make
that so. If you want a new category, you can add it. You want to
rearrange stuff? Go for it.

With respect to existing content now, allow me to prioritize:

1) The bulk of NuWiki now is the Nucleus documentation, which this was
essentially designed for. After I transformed all of the previous Word
docs, PDF's, and other sources into NuWiki, we had a framework for
future documentation and a visible change to how docs would be done in
the future. Harvey and Lee love this and have gone nuts with it,
generously adding content into nooks and crannies that would have
formerly been lost, but will now pop up at surprising and relevant
times in the future.

2) After getting the Nucleus docs in, I thought "what other content
could we fold in here to make people actually want to visit?", since
the tightly-focused Nucleus content was only of particular interest to
Nucleus clients and developers. QM was the most obvious choice. It
didn't have a champion in the third party space, it had not already
been done (ala EPick) and there was little risk of legal backlash (IBM,
Raining Data, etc.) So I took several of the QM manuals and
painstakingly transformed them into NuWiki. When it was ready for
public consumption, I announced it in the QM group, not knowing what to
expect, but bracing for the usual reaction to new things. Some of the
enlightened ones "got it". Others were frightened or possibly
intimidated by it, so they took the "she's a witch, burn her!"
approach. Still others took the posture "Cool, let's use it". What I
didn't expect was a complete dismissal from the QM factory, albeit
following a pat on the head for our "good effort". We don't take this
personally, and it doesn't daunt us from moving forward with our
efforts. We may have even been instrumental in a sea change at QM
central, as they introduced HTML-based docs in response to this. Still,
their posture is  curiously anti-open source when it comes to
documentation. Only external pressure and influence will likely change
this. After all, look what intense pressure does to coal. Hopefully, it
won't take as long to turn this into a diamond. None of us are getting
any younger =).

3) Using the above as a baseline for some content, I then started
adding "dogfood" sites. I took one of the professional organization
sites I maintain - The Eris Society - (erissociety.org) and
transmorgified it into NuWiki. It was greeted with much awe and
adulation at the annual meeting in late August. And it looks damn good
if you ask me. Oh, and it flat out works as a collaborative
application. About five days before the conference, I added a
ride-share page for people needing a ride from the airport to the
conference. Within ten minutes, people were already using it. Very
cool.

4) We are now adding clients that are not visible to the public light
spectrum. We have clients who are now using NuWiki for their own
proprietary and internal purposes to great success, and loving it.
Remember, we can segregate public from private content, so while
everyone uses the same engine, not everyone arrives at the same
destination.

Sorry for winding so long on this. Let me conclude by thanking you all
for your valuable suggestions and encouraging you to make this what you
want it to be. You want Pick content? Add it. It may inspire me or
others to help out and add more. You want QM rearranged? Go for it. We
are wide open to content. We can even provide you private space if you
want content limited to a select group. (Not a sales pitch, just for
the record).

As the UberWikiNerd behind the curtains, I see all content changes. My
first goal is to make it the best it can be, so I act as a WikiGnome,
correcting grammar and spelling issues, where appropriate, and
resisting the temptation to edit content to suit my own philosophical
or moral tastes. I monitor to make sure people play well together,
don't slander or use bad language, and try to avoid any copyright
issues. Other than that, you guys are welcome to make this into
whatever you want it to be.

Best regards,

Jon Sisk
Chief WikNerd
NuWiki.com

Responding to Jon's well stated position and clarifications:

OK, I'll pick up the gauntlet.  Here are my thoughts for specific changes
for the QM category.  If there's no objections here then I'll pitch this to
the QM forum before I start hacking.

Objective:
To modify the QM/OPENQM NuWiki so that it only provides material which is
supplementary to current documentation.

Under the current hierarchy the sections that contain major content are
QM:Intro, QM:Commands, and QM:Query.  These were transmogrified (love that
most appropriate word) from the then-current QM docs but are already
somewhat outdated.  To open these categories for new content, the existing
content for these categories will be moved to something more like
QM:PDOC:Intro, QM:PDOC:Commands, and QM:PDOC:Query, where PDOC will be a
new section named Product Docs.  A note will be placed on the QM:PDOC page
that the content in that tree should no longer be maintained but that it is
there for reference only, and that official product docs should be
consulted for basic product information.

The page "display=CATEGORY:" (null category = top level page) should not
need modification except for the addition of the PDOC subcategory.  The
page CATEGORY:QM will be modified to clarify the content of the various
subcategories.

Once this is done we/I will take another stab at soliciting content from
the OpenQM community, asking them to provide tidbits which are not found in
the official docs.  In private exchanges with Martin over the last week
I've been made aware of a number of such gems.  He's provided me with
insight into how certain commands should and should not be used, and he's
filed a number of enhancement (wish list) requests in response to some
queries and suggestions.

People can also document open wish-list items, bug reports, etc, but when a
change is made to the product, "someone" (originator of the change request
or otherwise) should flag a wiki change.  The wish-list item should be
removed and a wiki section of New Features should document the change.
Once the feature has been in circulation a while and in the official docs,
(or once a bug has been fixed) it can be removed from the wiki.  Again,
only notes that are supplementary to the official product docs should
remain in the wiki, so that this resource remains as slim as possible.

If anyone finds content that is already in the product doc, it should not
be removed immediately.  Anyone who wishes to contribute can annotate the
wiki content as "officially documented" or similar.  If such information is
easy to find the supplementary material will be archived.  If the wiki
documents material which is hard to find in the official docs it will
remain, and a wish-list item may be posted for better cross-referencing in
official docs.  If a wiki page has material which is also in the official
doc, proposals will be made to trim the content down to only what is
uniquely insightful and readers will be directed to the official docs for
basics.

Regards,
Tony (MV yenta)
TG@ removethisNebula-RnD.com

I don't have any problem with what I think you suggested above, but
would be curious how you would go about moving stuff to new sections.
Even for the great powers granted me by virtue of having access behind
the curtain, that is not trivial.

You are aware, for example, that this data is all in a big UniVerse
file, so those of us UberNerds can get in through telnet and SELECT,
COPY, DELETE, etc. But from a contributor's point of view, you can work
with only one item at a time.

Then again, maybe this speaks to the earlier concept discussed in this
thread about the value of "breadcrumbs". That seems to me to be the
hardest part of updating a massive number of topics at once. It
actually makes me long for the old prestored commands in the old Pick
Editor. Yes, the one that put the Ed in RetardEd.  From the other
perspective, modifying the references from the category items is not
that big a deal.

Whack away, TG. I'll look forward to seeing the results of your whack
job.

Or something like that. =)

Curious in Cal,

j.

Well then I guess that's yet another enhancement request for the software.
I'm surprised that no one thought of the idea of moving content once it's
been created, but in a "content management system" that sort of thing would
seem to be a requirement.

NuWiki is an application.  As a user I don't care what the concerns are of
the underlying environment.  If the designers actually hard-coded
categories as item IDs then they've made a cardinal error that the rest of
us avoid: never use data that's subject to change as an ID.  That includes
driver's license numbers, lastnames, social security numbers, phone
numbers, company names ... or category or page names.  If the environment
doesn't allow us to do this without assistance from the wizard behind the
curtain then the task simply won't be done.

I prefer to conduct whack jobs when out of state and no one can pin it on
me.  (Ooops, shouldn't give away trade secrets.)  Anyway, If we can't
re-assign content to a different category then this is a non-starter.  I
could create a new category for people to put in new content but I'll be
hanged if I'm going to manually find/move every page that seems of value to
the new area.

Let's see what comes back from the rabbit man and if some changes are made
to the software then we can take another look.  There's no rush.

Thanks.
T

Tony G wrote, and made me lay awake in the middle of the night
pondering my reply:

This author will take full responsibility for putting data into
item-id's from the onset, and will offer this explanation:

First off, all of my Wiki knowledge has a 2006 timestamp on it. At the
beginning of the year, I had no idea that this would be the year of
Wiki for me. So everything I have learned has been from studying other
Wiki's, most notably the 800 pound gorilla, Wikipedia. That said, if
any of my observations, conclusions or techniques are "wrong", then
only I am to blame.

The first thing that is obvious to me about Wikis in general and
Wikipedia in particular is that they are not dictionary-driven. Yes,
they all appear to be born Dictless. All data simply *is*. I offer to
explain this Zen-assessment by pointing you to the naming conventions
of Wikipedia, wherein only the subject is contained in the item id.
Hence, the topic on "Pick" can be found under the URL:

http://en.wikipedia.org/wiki/Pick_operating_system

With the "Pick_operating_system" portion being the part that I am
particularly interested in.

This is a fortuitous and appropriate example for this essay, as the
core operative word of interest to us is "Pick". I now refer you to
what Wikipedia has to say about "Pick":

http://en.wikipedia.org/wiki/Pick

The above link takes you to a "disambiguation" page to allow the reader
to choose which of the several dozen "Pick" topics they offer.

While I never knew the term for it, I have always attempted to adopt
"disambiguation" in everything I write. I figure if I can understand
it, it passes the first test. If my Mom can understand it, it passes
the LCD test and is ready for release.

So what I learned from this is that there are no "Category" pages in
Wikipedia like I built in NuWiki. You simply search for what you need
to search for, and hope you either find a hit or are lucky enough to
land in a topic that may take you to where you want to be. While I
enjoy surprises as much as the next nerd, sometimes I need to see a
menu to see what my possible entrees might be.

So my "cardinal error" started innocently enough and here come the
forensics.

The "order of one" access provided by Pick-Nelson environments is a
boon to access speed, at the price of having only