06/03/2008

Wikipedia, missing roundabouts and @if statements?

Some thoughts about our ever changing world and the new Web 2.0 philosophy:

Note 1)
Everybody knows Wikipedia and the huge and successful encyclopedia written and revised by users, right?

Note 2)
Yesterday evening I updated my TomTom ONE Regional V3 device with the MapShare technology: now I can report to others the errors that I will find during my journeys (missing roundabouts, close roads, etc etc), just clicking on my device display.
In fact today I reported two missing roundabouts and one wrong road name I found within Bologna, just connecting to Internet! And I also downloaded corrections reported by others.

Note 3)
Some days ago Giuseppe from DominoPoint.it wrote a post titled "Error Found & Fixed" : it's about an mistyped text he found about a @dblookup() function example inside the Designer Help. The funny thing is that the error existed since R5 and was corrected only in R8.
Roberto from IBM Italy took care about that little error, and now anybody can see the correction.

Note 4)
Just a few days ago I was teaching Lotus Notes/Domino programming to a young guy: I was talking about the importance of reading examples written inside the Designer Help and then I talked about the @isError() function: I found a small error in within the examples, both inside R7 & R8. Take a look:

4. This agent tests the return value of an @DbLookup statement for an error. If the @DbLookup statement causes an error, the agent returns the text "Not available."
FIELD Phone := @DbLookup(""; "Snapper" : "names.nsf"; "People";
@Right(Name; " ") + " , " + @Left(Name; " "); "OfficePhoneNumber");
@If(@IsError(Phone);"Not available")

As you can see, the @If() does not specify the "else" compulsary statement...

Conclusion
What would happen if the Lotus Help Designer was simply a wiki site? I guess that such errors would be corrected by the Notes community in just a few hours.... as for the Wikipedia.
Moreover people could add meaningful examples for all Notes functions, write some notes too.

Of course I'm talking abound writing revisions to documents initially written by IBM.

I guess that many people from the Notes community would be happy to better official documentation we read every day, especially junior programmers who really need good documentation.

Someone agrees with me? ;-)


14 comments:

Steve McDonagh said...

I agree ... what a great idea!
Perhaps something that we could run with on Bleedyellow , there are heaps of experts on there, a help resource for us by us... excellent!

Sherwin Delfin said...

I strongly agree!

Tommy Valand said...

You have my vote.

Putting the documentation online would also solve the problem of Help sometimes crashing Notes/Domino. :)

Roberto Boccadoro said...

I do not agree.
One thing are redbooks which, as you all know, are now written remotely and can easily turn into a wiki, another thing is the "official" documentation; the latter has to be written by IBM. What if someone writes something plain wrong ? This would be taken as "official" and could lead to very bad consequences. Should we, IBM, monitor every update written on the "wiki help" to make sure is correct ? Unfeasible as you can imagine. I am not saying we should not take advantage of your expertise, if you find something wrong in the documentation just tell us and we'll fix it. Other than the episode reported I did the same thing only yesterday for another small error a customer found in the Admin help; I reported it and it will be fixed in the next version.
Community based contributions have an enormous value, we all agree with this, but "official IBM" documents must be written by us and not by someone external.

Amy said...

Here you go:

http://www-10.lotus.com/ldd/dominowiki.nsf/

And yes, it's powered by Domino. :-)

Cristian D'Aloisio said...

Thanks Amy, I will take a look to the URL address.

Steve McDonagh said...

@cristian

Ping me at mcdonaghs[@]utvinternet.com if you think the WIKI link is viable..perhaps we can think of a way to use this to our advantage. Or you will find me in the bleedyellow ST server in the yellowbleeders public group

@roberto

Fixing the problem is fine, but these fixes usually dont find their way to the desktop in a timly fashion,if at all. Checking for and installing help documentation on a regular basis would be a bit of a chore.

I am not talking about changing "offical" documentation I am talking about adding to the resevoir of information available to the dev and admin community. This would be in the form of additional "user" documentation that is appended as separate documents at the endof your office documents. In the same way the PHP help works.. IBM give the HELP and the rest of us add to it with examples and/or clarification and/or problems. These additions would then become part of the resource available in addition that provided by IBM.

On a separate question ... V8.0.1 is lovely looking and is as far as i can see a VAST improvement on previous releases...however when are IBM going to improve the HELP UI? With the best willin the world it is a pain in the arse to use. For example.. Multi-tab it so you can flip between two topics quickly and easly.. the current sysem where the selection tree collapses when you go somewhere else is SOOOOOO annoying!

Steve




Steve

Roberto Boccadoro said...

@Steve
When I said I did not agree I was referring explicitly to our official documentation. What you say is correct and in fact you see Amy (and MBR herself in her blog) point you to the wiki. That's the place where what you and Cristian want happens. Notice though that even in the wiki the information provided by us in not editable, you can add comments but not change it.

Roberto Boccadoro said...

@Steve again
are you referring to the Help databases ? Have you tried the new help in Notes 8 client ? Too bad I can't add a screenshot here...

Amy Smith said...

@ Roberto - actually, you can edit any article that does not have the IBM logo next to it. :-)

Roberto Boccadoro said...

@Amy
this is what I said, or maybe I meant to say but my English need some improvement :-)

Mike Stewart said...

What's being said here supports some thinking we've doing along these lines. There are two needs: quickly updatable content, leveraging the wisdom of users, and trustable content. I can imagine experienced developers using the former, and novices sticking with the latter. How to provide both? A few models--non-editable pages but the ability to add comments; editable pages with corresponding non-editable versions (PDF or restricted wiki page); or a single editable page with updates highlighted (in different colors for IBMers and non-IBMers). Thoughts?

Mike Stewart, IBM

Cristian D'Aloisio said...

Hi Mike, take a look to some humble ideas I have: ideas

Thanks

Cristian D'Aloisio said...

Just for some fresh people just entering right now the Notes community, when Roberto writes this comment about MBR and her blog, he means Mary Beth Raven: see her post.