Parsing through observations of the last week, part 1: XPages

June 20 2010

The following observation was made about twenty different times, this particular one quotes Fredrik Stöckel:

A huge problem though with XPages at the moment is the (lack of) documentation, especially the API documentation, and the content-assist that only works if certain criteria are meet - and only in certain contexts (which gives you the (false) impression that it’s broken). It leaves you with the feeling that it’s a bit “unfinished”. It’s very important to provide good documentation if you want people to adopt XPages.
This seems like one that is pretty actionable and one that my extended team and I can drive.

I heard things like (paraphrased) the RedWikis are useless, the documentation is spotty, and most importantly, the code still needs polish.

So here's the question -- where are you looking for XPages documentation, what do you think is missing, and what sources should we draw upon?  And Declan, did you ever look into publishing a book of your 43-part blog series?

I liked the idea I read somewhere of marketing XPages without the Notes/Domino name.  That seems like a provocative thought, but the right kind of "think different" mentality needed today.

One thing I am confused on is whether OpenNTF is helping people learn XPages or not.  There seemed to be very mixed comments on this.  Let's not go down the rabbit hole yet of what applications are needed for Notes/Domino and where, just how you are learning XPages and what the opportunity is with them.  Let's keep comments here constrained to XPages.  Your thoughts?

Ed Brill | Highland Park, IL USA Category: Add/View Comments [72]

Post a Comment

  1. 1  Peter Presnell http://www.yellowverse.com | 6/20/2010 9:42:54 AM

    A) I would like to see comprehensive documentation of every parameter for every tag that can be used within XPage source code along with several examples that showed their use. Extend that to SSJS and then EL. This will allow me to get the most out of the many features there. I cant always wait for Tim Tripcony to discover what they are for and then blog about them.

    B) Declan's series is great as an intro, but takes a narrow slice through the product. I always cry when his examples don't overlap my need as I then have to find an answer the hard way.

    C) OpenNTF is absolutely helping by providing working examples that can be downloaded and inspected first hand.

    D) I absolutely loved the Deep Dive Webiner the XPage team put together last week. Perhaps they could develop one with each and every new release that focuses on just the new features for that release.

  1. 2  Nathan T Freeman  | 6/20/2010 10:02:35 AM

    Do this. { Link }

  1. 3  John Head http://www.johndavidhead.com | 6/20/2010 10:07:36 AM

    @2 Peter - no technology is every 100% documented - not Notes, not Office, nothing. And its rare to get more than one example. So lets figure out where to start.

    What I would like to see is IBM (directly, thru IBM Education, or working directly with XPages experts in the community) publish more tutorials like Declan's. First up, write a step by step on how to build the 8.5 Discussion Template. Why? It's on every Domino server that is 8.5 and higher. Then pick 3 or 4 other apps of different types.

    Next, work with folks who are doing XPages training today (Matt White, Tim Clarke, and others [PSC does at well, but don't want this to be a commercial]) to create recorded webinars. Audio, Video, Slides, and samples. Publish these on LDD - maybe the first one is free and the rest are purchased or IBM pays for them all; the details of how don't matter to me - and get them out there.

    OpenNTF.org is great in getting usable apps out there - but very few have details on how they were built. Maybe pick those apps as the samples to document and build training around.

  1. 4  Christian Drenth http://blog.clearitconsulting.nl/ | 6/20/2010 10:11:57 AM

    Detailed information about every tag and propery is an absolute must, context dependent (F1), with working code examples.

    Extended blog posts like Declan's series certainly help and are a good starter. As well as all other known XPages blogs and videos. OpenNTF is also a good resource, no doubt about that.

    A last thought: A best practices resource with code snippets and maybe even reusable custom controls.

  1. 5  Jeremy Hodge http://www.hodgebloge.com | 6/20/2010 10:19:17 AM

    I want to take a bit of time to really think about this to give you all some good feedback, but up front, here are a few observations:

    In addition to the API documentation being incomplete, its hard to find, and use. Specifically a few things would help designers Learn when designing an XPage application ... a couple of these are design issues not specifically documentation issues, but good documentation you can't get to isn't good either

    - from the source window, I get no code assist, no reference and no Outline .. If I want that I need to be in the Script Editor (which I personally hate to use ... it takes me out of context of the code, has focus issues if it ever loses focus [click away and back, then keys like delete, cut, paste, etc affect the source code window, not the Script Editor])

    - when I am in the Script Editor, There is no contextual way to get help on something, either from the source window, or the reference outline. When I open help (by pressing F1) If I go to the index and search for "NotesDocument", the name of a SSJS class, for example, the index can't find it, which means I have to go to search, then the first one is usually the XPages reference. But its not a detail of the class members, properties, etc. In fact it lists a bunch of properties that aren't actually publicly available, like "NoteID". You can't actually reference NoteID. You have to use the property getter getNoteID(). Which you don't know unless you click into NoteID and read further there. Major confusion for someone trying to learn. The help is also very wordy ... at the class level, a list of proertys/functions/etc would be better so you can drill down to detail.

    - I think there also needs to be alot spent on "conceptual" issues. Moving from traditional domino development to XPages is a pretty big change. You have to think differently about the sequence of events when things happen, how partial refreshes work, etc. I've had several discussions with developers that have come in with questions from the XPages Blog, and a lot of the questions stem from a misunderstanding of how XPages work. The sticking point seems to be they are trying to treat an XPage the same way a classic Notes form works, which it just doesn't. There should also be basic documentation around some web dev concepts like CSS styles and classes, client side versus server side, etc.

    - Everything out in the community helps ... OpenNTF, the wikis, blog posts, etc ... but the topics on all of these are usually very narrow and specific, or are "tips and tricks", Dec's series is really great, but even that starts out part way through the story ... there is no "how to get started with Xpages" that I have found ...

  1. 6  Peter Presnell http://www.yellowverse.com | 6/20/2010 10:36:23 AM

    @3 John. I actually think IBM/Lotus came pretty close when they documented LotusScript. Apart from a few "undocumented" features pretty much every class and every property/method is documented often with multiple examples. A large number of people (including myself) where able to teach ourselves how to program in LotusScript and I think the on-line documentation was a big part of that.

  1. 7  Nelson Morris  | 6/20/2010 10:47:48 AM

    I like idea of some well documented sample applications that point out coding techniques along the way. The other day, I started to get my feet wet with Xpages. I stumbled on things like validating a radio button, and how to dynamically require/hide a field/label based on the value of another. I discovered there are a lot ways to do these tasks, but I didn't know enough to know what was the most elegant technique to do so.

  1. 8  Ben Poole http://benpoole.com | 6/20/2010 10:55:57 AM

    For someone looking to get started, the obvious place to me is Matt White's "XPages 101" ( { Link } - apologies for the gratuitous plug).

    With regards pushing the XPages message beyond the Lotus world, that strikes me as being a fantastic idea: this stuff really needs to open up IMHO.

  1. 9  Alan Hamilton  | 6/20/2010 11:08:14 AM

    As well as proper documentation at a level we have seen from the likes of Apple, it needs proper advocacy by senior people in the IBM Notes team. Sorry to say it but { Link } is a good example of what I'd like to see.

  1. 10  Jason http://www.aqu8.com/Lotus-Notes-And-Domino-Reseller-Program | 6/20/2010 11:16:49 AM

    @3, right, no software is fully documented... but there still isn't any excuse for.

    I'm pretty sure someone at IBM has an MSDN subscription. There's something Bill got right. That's what we need, well organized content with the biggest provider of the content IBM... then we can contribute as well.

    Screen shots are needed too in the documentation. 95% (un-scientific estimate) of documentation coming from IBM is text only and it's very useful to actually show people with screen shots.

  1. 11  Erik Brooks  | 6/20/2010 11:17:27 AM

    The XPages-only "Designer Lite" probably came from my blog entry.

    { Link }

    The #1 place I, and much of the dev community, look for help on ANY technology is an O'Reilly book. The minute you have one, your tech gains instant credibility.

    The #2 place I'm looking for help is similar to @5, i.e. when I press F1, or with auto-complete enabled I want it all over the place, etc. etc.

    On the XPages "deep-dive" presentation (which was very good, by the way) they mentioned an IBM XPages book would be out by the end of the year. That will probably help immensely, and likely should have been out a year ago.

    I love John's idea @3 of a video/step-by-step to build a native Domino template.

    Also, Ed, I know you guys are driving a lot of the Dojo team with features, bug fixes, etc. *THEIR* documentation is abyssmal. www.dojotoolkit.org (finally) looks pretty at first but as you dig deep looking for info it's woefully inadequate.

    I'm bringing this up because you guys simultaneously need a thriving Dojo community. It's the JS toolkit for the entire IBM/Lotus portfolo, and if/when you do release an XPages "Designer Lite" all of the non-Domino developers embracing Dojo (and there's quite a few already) are only a hop-skip-jump away from trying out XPages.

  1. 12  Erik Brooks  | 6/20/2010 11:34:18 AM

    After re-reading, some more clarification:

    An O'Reilly's book is the #1 reference for any tech I don't already have some experience with. E.g. if I wanted to learn Ruby-On-Rails and didn't know it, I'd start there. They have great high-level overviews down to specific API calls. This is one of the main way you'll attract totally-new developers and is still very useful for devs experienced in the tech.

    The F1/context help is for "once you're in there" developers who already have at least some fledgling experience with the tech (e.g. legacy Domino devs).

    John's step-by-step video helps both groups.

  1. 13  Mark t Hughes http://Hughesconnect.com | 6/20/2010 11:35:58 AM

    I learned ls via another developer and great documentaion and examples in the designer help file.

    When i started Xpages i went to the help file to not find much informatiin, at that point google and PL were my friends. I somehow stumbled across some people on the xpage design team, namely Paul Hannan, who were of great help. If they did not know the answer they would try to get one for me.

    When i asked on my blog via PL if anyone had seen a way to do a view picklist no one had, though i was given some advice in what direction to go. I finally figured it out and bloged the solution. Amazingly i have had more than 10,000 hits on that post alone.

    The community is helping(there is a great name picker out there), but it seems some things we took for granted in the client( like view picklist) did not have a counterpart in Xpages.

    I would love to see documentation like that of LS in the help file as well as more controls in designer.

    Ps. Thanks for everyones help that they have given either by IM, email, or blog.

  1. 14  Paul Withers http://hermes.intec.co.uk/intec/blog.nsf | 6/20/2010 12:16:00 PM

    I must add my voice to those of other developers and say bring XPages help up to the same standard as lotusscript code. A perfect example that I had to ask on the forum is how to pass multiple keys to a getDocumentByKey in XPages code. There is no example in the help about how to create a vector. That's fine if you're coming to XPages from a Java background. Remember that most Domino developers are not. Equally remember that some will be, so they will need more support on standard Domino. I think R6 had a pictorial version of the Domino Object Model available from the welcome screen of Domino Designer. For a Java developer (and I was with one who is learning Domino last week), having that interactive diagram would help them.

    The script editors are better in 8.5.1 since in FP3 it seems that changes made in the source pane are instantly available in the script editors. That makes it easier to switch between them when you're not sure. If the source pane can use content assist on SSJS, that would be wonderful - most of my coding is now directly in the source pane, and I think other developers will do too as they become more au fait with the code and the ability to drag and drop controls into the source pane in 8.5.2 beta. However, I can envisage that being rather challenging.

    OpenNTF is a good, but I see it as a resource for custom controls, sample apps. I learn a lot from those apps and controls, but I don't consider that it's primary intention.

    The course on the wiki is used by a number of developers, but a couple of additional exercises for what's new in 8.5.1 and, when due, 8.5.2 would be beneficial and keep it fresh.

  1. 15  Rob McDonagh http://www.CaptainOblivious.com | 6/20/2010 12:17:11 PM

    Videos are NOT a substitute for documentation. Every time I look something up on one of the wikis and the "answer" is a video, I give up and look somewhere else. I don't have time to wait for somebody to MAYBE answer the one question I have, when text-based documentation has this magical, amazing "Find" feature. You want videos? Fine. But don't for a second imagine that the presence of videos means there is documentation. Video + documentation = awesome. Video - documentation = pathetic.

    To all those who've pointed out how useful the LS documentation was to them when they were getting started: +1.

  1. 16  Russell Maher  | 6/20/2010 12:23:31 PM

    Ed,

    SHORT VERSION:

    Thank you for asking. Here is how I get XPages help:

    I search the documentation for specifics then Google for how to create actual functionality (or find out where something is a bug so I quit wasting my time).

    At the very least the shipping documentation should provide details on everything that actually appears within the XPage toolset and there should be solid useful examples of how to use all of it.

    LONG VERSION

    Thanks again for making an effort on this. This is a very productive issue to try and tackle. Paul Calhoun and I are in the middle of preparing content for "a well known technical magazine"'s upcoming XPage seminar (which should be coming to a city near you soon!!!!) ...uh, and consequently I have actually been thinking a great deal about the "where do you go to get XPage help" topic.

    When I first started XPages in April, 2009 I did it this way...

    1. I tried the documentation first. Basically useless for first-timers.

    2. I used Declan's excellent series and read it and used it while I was developing.

    3. I read a lot of what John Mackey has written.

    4. I read the Domino Application Wiki

    To be honest I found that what I needed to do with XPages for the first year nobody else had even considered doing even though I was doing things we have been doing for years in Domino. That was really frustrating for a beginner.

    Now, over a year later and having developed several (what I consider to be) medium complexity XPage apps I do it this way...

    1. I look in my own code for how I did something similar before for an answer.

    2. If I need to know something that should be in the documentation, I do a search in the Eclipse/Designer help.

    3. I Google and Google takes me mostly these days to content written by Matt White, Paul Leedy, Paul Hannan and the XPages blog.

    I am happy to report that what I needed to know a year ago others have apparently needed within the last six months and have documented their various solutions. That's the good news. You already know the "bad" news or else you would not have posed your question.

  1. 17  Jose Zaldivar  | 6/20/2010 12:34:37 PM

    In our company we are slowly adopting Xpages - 3 steps forward, 2 steps back. It is very tough to learn a technology without having a central repository of good documentation, examples, etc. I wish IBM and bloggers would use the Wiki to post their entries or at least the abstract to their own blog entries. With so many blogs out there, you only get ahead in Xpages by knowing how to search on Google or bookmarking every blog that you come across that relates to Xpages. My RSS feed is packed with entries.

    My wish list for Xpages:

    1) Use the Wiki as the main repository to learn Xpages. If you are into blogging about Xpages, please post an abstract in the Wiki so we can find you!. Please, please repond to comments made in the Wiki. I am in favour of the Wiki as anyone can make edits to existing content, correct it, and add to it to keep it current - you can't do that in blog entries!

    1.1) IBM, please make the Wiki easier to use! Can we have a decent web editor? I have tried posting rich content, with images, and videos. It is virtually impossible to create content quick using that web editor.

    2) Embrace the openNTF to upload examples. It is definately a the source to get good stuff. But please post more documentation or at least links to the blogs where we can have discussions. I still not sure why are not able to "donate" directly on the OpenNTF to developers who bothered to create these great examples and help us be more productive.

    3) Make the Designer help more powerful with links to video samples for using specific functions. If you have used Adobe products, you would be familiar with the full library of videos they have posted on using their product.

    4) Are we still using the 8.5 discussion forum? I am no longer sure that is being followed much these days.

    5) Post and have more webinars. If we had monthly events where some developers can showcase some appps, that will be great. It is way faster to show an app than it is to write about it. If these webinars can be recorded and published later the better! Lotuslive is a great method to deliver these sessions.

    6) Get rid of the old ugly looking templates provided by default in the Notes Client. It is hurting us. Have them developed in Xpages!

    7) Use youtube to post video samples. It is fast to download and we are able to post comments. Everyone knows Youtube.

    Xpages is a new thinking, a new approach to programming in Lotus Notes. If we can develop complex apps the old fashion way, we sure can learn Xpages!

    I am hoping we move Xpages forward must faster without any going any steps back.

  1. 18  Ed Maloney  | 6/20/2010 12:50:03 PM

    Perhaps it's just me, but I would love to see IBM commission an XPages update or equivalent to the Oliver/Benz Notes 6 Bible. This book is a comprehensive introduction to Notes&Domino development as well as a useful how-to guide for common application features. I also like the idea of renaming XPages since the value of the legacy Notes brand doesn't seem to be helping market perceptions.

  1. 19  John Head http://www.johndavidhead.com | 6/20/2010 1:19:57 PM

    @15 Rob, I agree with you 100%. Documentation needs to continue to be updated. It should be documentation + videos. The only issue is most people don't get updated documentation unless it's thru a release. Videos can be pushed outside of the upgrade cycle. So can wiki updates, samples, and anything not in the software kit.

    I don't want this thread to turn into a 'here is what Company X does better' but I think IBM needs to take a lead from others. IBM needs a full time employee who's job is to generate content for the Xpages crowd. This person needs to be technical. They need to have access to the XPages dev team. They need to have a blog and be tasked to generate content. On a weekly basis. Not in the lines of the Lead Manager applications - but a sample a week at minimum. Any they should be tasked to read the blogs and forums. Answer questions. React to 'how do I do this?' posts and use that for their content creation. They should be at every user group event possible and should become the pipeline for getting the community up and running on XPages. If someone has an issue, that person sends a link and instructions on how to submit a PMR. This person becomes the voice of XPages and works with IBM and the community to determine the needs and fill the holes.

  1. 20  Corey Davis http://www.conxsys.com | 6/20/2010 1:45:44 PM

    I am going to "double-down" on Nathan's comment (@2): do this { Link } Do it with Lotusphere. Charge us a nominal $99 fee like Apple does to become an "official developer" and then do this. LS videos should not be a profit center.

  1. 21  Sean Cull http://www.seancull.co.uk | 6/20/2010 2:13:22 PM

    @17, I am at odds with Jose's view on Wikis.

    The Wikis should be a distilled set of best practice otherwise they become the sae as the existing forums

    If you follow the link to "Xpages in the Client" it is of very limited use.

    { Link }

    I admire peoples efforts but imagine what it will look like in 2 years time ?

    Sean

  1. 22  Corey Davis http://www.conxsys.com | 6/20/2010 2:26:50 PM

    Regarding my previous post (@20) I must apologize. You may not be able to see what I referencing without an Apple Developer account. But, Apple has posted videos to every track done at WWDC 2010 to iTunes. I would like for IBM to do that with Lotusphere.

  1. 23  Mark Barton http://www.markbarton.com | 6/20/2010 3:04:41 PM

    To be slightly different may I recommend - { Link } as an example of how much effort a manufacture puts behind there software and no stupid $99 fee. You can see there banner adverts everywhere pushing the free training.

    Books - there needs to be books even if there written by IBM specifically on XPages. A wiki doesn't cut it.

    +1 for Matts videos.

    I would also recommend a lite designer which is branded in a different way - drop the legacy design elements and how about a free domino express server which only supports XPages? Make this lite designer enterprise ready: Unit testing, Network Monitoring, Source Control Systems. Right now I find Notes being slammed because of compliance and one size fits all SDLCs.

    Personally I would also like to see examples which are not based on using Dojo but instead use JQuery. I appreciate this would reduce some of the functionality, but by how much?

  1. 24  Tim Tripcony http://www.timtripcony.com | 6/20/2010 3:11:50 PM

    For those who haven't clicked the link Nathan posted, it's an article about a 10-week course on iPhone development that Apple teaches at Stanford. Yes, you read that right: not only is it a university course dedicated entirely to a vendor-specific technology, but it's taught BY that vendor - not Stanford professors, Apple employees are AT Stanford, teaching the course.

    While this doesn't directly address the documentation issue, it does indirectly: were someone to design a college course for teaching students how to develop XPage applications... and then publish all of the lectures... professionals already in the field would have a perfect mechanism for learning the technology. Just like the students, they could spend just a couple hours a week, starting from an assumption of no prior knowledge, learning very basic, fundamental concepts... and, in a scant two months, they'd be writing fairly advanced applications.

    Oh, and in the meantime, we'd be sending the signal to existing students - and the market - that (as I phrased it in a comment on my own blog) Lotus technologies DESERVE to be mainstream. In my opinion, what makes other technologies mainstream and leaves our beloved platform considered niche, quaint, even archaic, is that other technologies are treated like they're mainstream even before they become so: you can take college courses dedicated entirely to that technology; you can find hundreds - if not thousands - of books about it. If Apple can convince Stanford that it's okay to let their own employees teach a course at Stanford about their own technology, I have no doubt IBM could win the same argument about XPages.

  1. 25  Kevin Pettitt http://www.lotusguru.com | 6/20/2010 3:47:22 PM

    Ben Langhinrichs's comment #60 in Ed's initial response ({ Link } ) to this uproar sums up my major concern re: XPages quite well:

    "People want to install a product and see the value immediately. Then, they want to see incremental additions they can get with a bit more effort. Finally, they want to know that the product is capable of much more.

    IBM has somehow slipped away from the instant value and the incremental additions and focused on the capability to do more. XPages may be great, but do they offer me value out of the box? Give the executive something to fall in love with day one."

    Just to be clear, the "instant value" proposition *should* be achievable by the same "power user" contingent that made Notes apps so popular to start with. All the focus on appealing to developers outside the Lotus world is great, but cannot be the whole story.

    Working sample apps are going to be the main vehicle for that, so no avoiding rabbit holes I'm afraid.

  1. 26  Ed Brill http://www.edbrill.com | 6/20/2010 3:53:04 PM

    @25 I just don't want to discuss working sample apps in this thread. I get it, but let's save that discussion. It is a much harder one and I need more input/thought.

  1. 27  Patrick Kwinten http://quintessens.wordpress.com | 6/20/2010 4:16:09 PM

    I want an quality XPages only book. And soon. Because I am going on vacation and want to have something interesting to read at the beach.

    @ this moment I attended a course organised by Fredrik Stöckel and we agree, documentation is lacking. Hell there are even no exampels included in the Designer help for JS @Functions.

    I collect everything written in the blogosphere about XPages in a Notes database. Some 200 plus documents right now. Where can I drop it?

  1. 28  Patrick Kwinten http://quintessens.wordpress.com | 6/20/2010 4:18:23 PM

    the levels of information should be wel organized from beginner - medior - advanced XPages developer

  1. 29  Nathan T. Freeman http://nathan.lotus911.com | 6/20/2010 4:32:00 PM

    "If Apple can convince Stanford that it's okay to let their own employees teach a course at Stanford about their own technology, I have no doubt IBM could win the same argument about XPages."

    Oh, I do. Practically all of Apple's technology was invented at Stanford. I bet Lotus has zero relationship with them.

    However, perhaps a similar class at Harvard or MIT would be possible. :-D

  1. 30  Kathy Brown http://www.runningnotes.net | 6/20/2010 4:57:16 PM

    I agree with much of what has been said. Documentation is a must, especially since so many of us learn by trying, when you can't make it work, you look to the help. When there isn't adequate help, you stop trying.

    I think there are different tracks for learning XPages. There are those of us like myself, who are coming from Notes Client development and need a "transition" type of training. Those types know Domino, but not the web.

    Then there are those developers who have loads of web design understanding and need the transition to Domino. I feel like a lot of the (limited) amount of information out there is geared to these folks, but still needs to be formalized to insure all the gaps in the training are filled.

  1. 31  John Head http://www.johndavidhead.com | 6/20/2010 4:58:32 PM

    @23 I don't think you will ever see IBM write about anything other than dojo. Why? because it's in the box because IBM legal has vetted it. It would be a big effort to replace dojo with anything - since it is so deeply integrated. Any effort around that will have to come from the community itself.

  1. 32  John Head http://www.johndavidhead.com | 6/20/2010 5:01:11 PM

    @25 Funny enough, I was just talking about client side only apps with a customer today. They used to have apps all over the clients because anyone could create a local replica from the templates in the product. Today, they lock that down with policy. The policies weren't there to prevent this in 4.x time frame. I wonder how many companies use that policy - because I bet the 'create new database on server' setting is in place at the majority of companies. Something to think about in that larger discussion.

  1. 33  Erik Brooks  | 6/20/2010 5:10:55 PM

    @19 - There is updated documentation available at the IBM publib.boulder site:

    { Link }

    What about embedding some interactivity to that site with the shipping Designer Help? E.g. If I push F1 in Designer to bring up help for GetDocumentByKey, ;-) it could also pull in the following in the same window:

    - any *updated* help from IBM's site

    - links to any related, public SPRs about the function/method

    - links to any IdeaJam-related posts to the function/method

    In essence it would be a dynamic, pseudo-open version of Microsoft's MSDN help integration with their products, but even better.

  1. 34  GarryL  | 6/20/2010 5:22:03 PM

    Documentation definately an issue - our guys do exactly what others have done and scour various web sites and blogs. And there is definately a different type of leaning for those coming from classic Notes to those who know web stuff (@30)

    @11 Would agree with lots of what you said. NSF is the jewel in the crown of Notes and is really well placed to take advantage of all the NoSQL stuff and explosion in unstructured data happening presently. Maybe you could take the whole XPages/NSF package so you can easily pop it into any webserver be that Apache, IIS or Domino?

  1. 35  John Turnbow http://www.recondite2.com | 6/20/2010 5:22:50 PM

    Just an extra sound off on Documentation.

    No comparison to other products.

    Look at how well documented and example driven that the Formula and LotusScript are. The documentation there has always been great! (Wish you guys had the technical writer that did that!).

    Then compare to Xpages, just leaves one in "agony". Then search the web and you "might" find the help you need and might not. To me the documentmentation is unfinished work and sadly lacking.

    Look for training, TLCC is a good start, xpages101 good as well to get you started. When you start actually using the product and go beyond you find how little documentation and help there is.

    Another thing I would like to see is a CSS and THEME Generator for Domino, I believe this should be part of the product, since, after all we have css and themes.

    Oh, and where are the books on Xpages? I can buy a book at Barnes and Noble on most any competing technology, but not Xpages (or R8.5 -yes we can buy online, but nothing for Xpages).

  1. 36  John Head http://www.johndavidhead.com | 6/20/2010 5:24:00 PM

    @33 i am all for that if you can get that thru the IBM machine. Id start with something on-line first. They can always copy and paste it into the official doc later. Heck, if I could get IBM legal permission, I would take the documentation today, import it into the IBM XPages Wiki template, and post it for community editing. Now that I type that, I will send off an email to ask to do just that.

  1. 37  Bruce Langner  | 6/20/2010 7:38:58 PM

    Most of my career in Notes development has been Notes Client, with a smattering of web dev. I am now responsible for web enabling a sophisticated Notes client application using XPages. The official documentation is inadequate to say the least; some parts are brilliant but the fundamental absence of basic stuff is frightening in a professional product released by IBM. The organic resources available on the internet are ad hoc and represent the person making it available rather than a coherent view of the technology. I spend too much time trawling through bookmarks and search results trying to piece together assistance with the task in hand. If this problem is to be fixed the solution needs to be comprehensive, from cradle to grave as it were. It needs to assist beyond the initial learning phase. I have experience with highly complex Notes client applications and at the moment am having unacceptable delays in implementing objects and workflows in XPages that should be straightforward. I am not a guru or a geek, and I shouldn't have to be to get ahead with XPages. Many thanks go to all those people who have begun to fill the void, and whose contributions have helped me to understand the new tech. I hope Ed's call will result in a coherent set of resources becoming available soon.

  1. 38  Tim Tripcony http://www.timtripcony.com | 6/20/2010 8:54:37 PM

    One other thing to consider in advance of the official release of 8.5.2: while the usual disclaimer applies, that anything we see in beta may or may not survive the beta process... assuming it does survive, the biggest change to XPages that will need to be documented is the arrival of the extensibility API.

    I'd like to make two key points about this:

    1. Some documentation about the extensibility API has already emerged on the Application Development wiki:

    { Link }

    I think that's fantastic: the feature isn't even gold yet, and already there's publicly available information on how to use it - from some of the very members of the engineering team who developed the feature, no less. Outstanding.

    On the other hand, the first time that Nathan and I attempted to create an XPage control library by following those instructions, my attempt succeeded and his failed... and that, as you might imagine, is a rare occurrence. The reason? Because there are two different articles explaining the same process... with conflicting instructions. One works, the other doesn't. I much prefer the "living document" approach to documentation to the "wait three years for the next major release and then you'll get updated documentation" approach. But there still has to be a vetting process; if one developer's exploration of a new feature is successful and another's isn't purely because there is conflicting documentation, the entire platform runs the risk of being perceived as more difficult or less reliable than it really is just because some people used the wrong instructions.

    2. The whole point of the extensibility API is that we can do *anything* with it. If we have a pet peeve about the way the standard DatePicker works, for example, we can "extend" the DatePicker to create our own MyCustomDatePicker control that works exactly the way we want it to. If we think IBM should have included a CalendarViewPanel on day one in 8.5.0 and are annoyed that they still haven't, we can create our own and make it behave exactly the way we want to. No more excuses. No more whining that the platform doesn't somehow out of the box match every last procedural nuance specific to my individual business needs in addition to doing the same for every other customer they're trying to please... we can "fill in the blanks", so to speak, often with very little code of our own.

    Heck, on Friday, I took a control that IBM provided just as one example of how to use this extensibility API - an example that extends the behavior of the default ViewPanel - and extended *that* because there was one specific thing their example didn't do that I needed it to for something else I wanted to try. It took 8 lines of code. Not 800, not 80... 8 lines. Done. Works precisely how I had hoped it would. And, because I was extending IBM's extension, I can still use their extension in all of the many other places where it will already be useful without needing the one feature that my further extension provided.

    So this is all super-useful, and just really blows the lid off of what we could already do with custom controls, not to mention all of the JSF goodness that's hiding just below the surface of what Designer does for us visually without us having to actually understand JSF.

    And herein lies the challenge: how do you document "you can do anything"? The examples I've already seen (which include the ViewPanel extension I alluded to) are very encouraging, because they're actually very useful; as well-documented as the Formula/LS API's have always been, a lot of the example code demonstrates what you can do, but in contexts that would never come up in my own applications. I can assure you that the example extension controls IBM's already provided, on the other hand, will be heavily used in my applications - one of them, in fact, will probably be a key underpinning of my primary current endeavor. So that's fantastic, but part of what makes them so useful as provided is that they're doing powerful things, and none of them came with a detailed breakdown of exactly *how* they're doing those powerful things... you have to dig deep into the source code - which is all written in Java, of course - and retrace IBM's steps to figure out exactly what you'd have to do to create your own extensions. So we've got documentation on how to create and deploy a library of extensions once we've written those extensions, but we have to reverse engineer the example extensions in order to figure out how to write our own extensions, and most developers simply aren't afforded the luxury of time to do that.

    In short, how do you gently tell the customer base, you can now make this platform do just about anything you can imagine - and make it do it precisely the way you want it to - if you'd just bite the bullet and learn Java? I've occasionally tried myself, but always feel like I'm coming across as unsympathetic... not to mention hypocritical, since it's been less than three years since I was the one saying, "I don't want to learn Java. Java is overkill." Well, I know now that it's not overkill, so I got that goin' for me, which is nice. But it's a hard sell to people who just want to be able to drag and drop an icon onto a visual representation of the page they're trying to create and have it just work the way they intend it to. The documentation on how to push past that desire to the absence of limitation that lies just beneath it is going to have to be simultaneously thorough, accurate, and gentle. To be perfectly honest, I don't envy whoever is assigned that task.

    But the extensibility API proves John's point: you can't document 100% of what can now be done with XPages without absorbing every example of what can be done with Java into your own documentation, which would be ridiculous. There has to be some kind of seamless bridge between instructions on how to do what is entirely specific to Domino (writing your own controls and then actually using them in a "real world" XPage application) and the plethora of information that already exists on how to use what's already been written by millions of Java developers - who know nothing about Domino - in our own applications. And... if, in the process, that brings some of those other developers into our own fold, hey, the more the merrier.

  1. 39  Erik Brooks  | 6/20/2010 9:40:59 PM

    @36 - John, you rock harder than Hallowed Be Thy Name. Let us know what comes of that!

    @38 - You bring up a very good point about current Domino devs trying to embrace XPages: they've had problems because there are many RAD-concepts in legacy Domino dev that don't have a just-as-easy equivalent with XPages.

    For example, one of the first things an old-school Domino dev would want to know how to do is "how do I put a view on my XPage?"

    The ViewPanel control out-of-the-box with 8.5.0 had many aspects (indentation, totals, etc.) that just didn't work. Even in 8.5.1 there was still some more work that needed to be done by IBM just to get it up to where legacy views on the web were 10 years ago.

    As Tim describes though, there's a whole lot *more* you can do with the ViewPanel (even in 8.5.0) without diving deep that you could *never* do with legacy Domino web views. But the bugs/problems/incompleteness of major standard Domino controls cause a significant barrier to legacy Domino devs trying to maintain their RAD-ness while learning a new technology.

    Anyway, where I'm going with this (since we're discussing documentation) is that it would be great to have a "translation" guide showing "how to do old-school technique XXXX on an XPage." This would be a very handy transitional piece, a "cheat-sheet" if you will, documenting things like:

    Views - enabling restrict to category

    Forms - "automatically enable in edit mode", put a link on a page, etc.

    Such a document would not only be helpful for Domino devs in transition but it could also be very revealing, identifying areas in XPages where they lack the RAD-ness of legacy Domino dev.

  1. 40  Rob Brown  | 6/20/2010 10:05:16 PM

    Declan's blog series was the best jumpstart on Xpages. I found it useful to PDF it into one big file. What would be great is for IBM to make use of iTunes U for videos that work through Declan's "Xample". Also -- the comment last week about separate branding of Xpages is a great idea. We know it's the Notes we love, but separate branding of Xpages is a great opportunity to capture those who just don't get Notes.

  1. 41  Raghupathi Reddy http://lotusdominoweb.blogspot.com | 6/21/2010 12:02:35 AM

    Does XPages included in lotus notes designer help?

    Lotus notes designer help is the first place i look for any help.

    So, something like designer help would be great.

  1. 42  Nathan T. Freeman http://nathan.lotus911.com | 6/21/2010 12:06:10 AM

    @41 - When you press F1 in Designer, yes. When you open help\help85_designer.nsf on your Designer client, no. Well, there's 23 entries in an FT search for Xpages. That's as compared to over 5000 for, say, Lotusscript.

  1. 43  Julian Buss http://www.youatnotes.com | 6/21/2010 2:27:03 AM

    I'm late... nevertheless, here are my comments:

    - the Domino Desigenr Wiki is useless mostly because of the problem that it contains stuff about many different topics, with SOME XPages related stuff among them.

    It's very hard to find something in it. While developing, one has mostly questions like "how do I implement this and that...?", so one is looking for ready-to-use samples.

    Thats the very reason why I started an XPages Wiki of my own at { Link } . It contains all tips and tricks and ready-to-work solution I found during my work. That's what a developer need during the work.

    - for *learning* XPages you need a course like Declan's phonebook sample. Perhaps you can give Declan a fee and publish it under IBM's brand.

    - Indeed, the product documentation is mostly useless. I don't use it at all.

    Take the LotusScript documentation as a reference: it explains the whole API, has code samples for everything and many useful additional explanations.

    The XPages documentation should be as good as that.

    - OpenNTF code is good, but only for devs who are already in the XPages world. When you want to learn XPages, most samples are hard to use because the installation already needs XPages knowledge.

    - marketing XPages idependent from Domino is not a bad idea. Perhaps there can be some sort of compromise like "XPages (and then in small font) powered by Lotus Domino".

    As of today, when one of our customers wants to start XPage developing, it goes like this:

    1.) they book a two or three day course for one of our trainers

    2.) in the course we start to create a prototype for a real-world app

    3.) during the course and after that the documentation we use is:

    a) xpageswiki.com

    b) xpagesblog.com

    c) Google or the XPages restricted search at searchlotus.com/xpages

    The XPages documentation in Designer is not used at all.

  1. 44  Richard Hogan  | 6/21/2010 4:47:48 AM

    My resources for learning LotusScript and Formula were:

    1. Designer Help - which covers all aspects of LS and formula, documented in a predictable way which is complete and searchable, and includes multiple helpful examples per topic (copying a piece of example code from Designer Help is something I still find useful all the time).

    2. Notes forums - great for anything I can't figure out from Designer Help.

    3. Google - when the first two don't help me Google will give me blog entries and other useful info.

    This worked very well for me. For other people? I don't know, but would be worth checking out.

    For me the ideal would be:

    - Designer Help updated with XPage documentation, and examples, to same standard as LS documentation

    - An online main XPages Documentation site, with a relatively small number of links to other resources.

    - Linked Resources to include a) Designer Help online, b) XPages forum, c) XPages Wiki, d) Videos, e) Resources like Declan's series, f) Page for Misc Other.

    - A search on the main XPages site to return material from all main linked resources

    - Videos max length 10 mins (I agree with @15 that videos are no substitute for text documentation)

    Also helpful would be at least one XPages application, fully supported by IBM, with code well documented and reflecting best practice. This template to be available on OpenNTF (where it can be updated) and also shipped with each release (for anyone who has never heard of OpenNTF). The application should look good, shine from usability point of view, and be useful right out of the box so it gets put into production and says to everyone in the org 'look what XPages can do'!!

  1. 45  Declan Lynch http://www.qtzar.com | 6/21/2010 6:31:50 AM

    Seeing as you asked if I had considered converting my 'Learning XPages' series into a book I had better give an answer.

    After finishing the blog series I did consider it and even started converting into book format, however as I was doing this I was still learning XPages and I realized that there were some portions of the blog series that I would do differently as I learned new techniques. Rather then have techniques that would not be considered a best practice in book form I finally decided to just leave the blog series as is.

    The series is still a great jumpstart for the beginner XPages developer and it's FREE. It still gets a lot of hits every day from all over the world. Once you have gone through the series I'd advise you look at XPages101.net for more training.

  1. 46  Fredrik Malmborg http://www.replikera.se | 6/21/2010 7:58:20 AM

    In the beginning of my Lotus experiences I got the R5 Best Practices yellow book. It rellay got me into understanding how to do things. If there was something like it for XPages it would be just fantastic.

  1. 47  Barry McGovern  | 6/21/2010 8:16:32 AM

    This is pretty simple in my humble opinion. Finish the xPages help documentation to the level of existing Lotusscript/@Formula documentation. That's it.

    Wikis, Videos, OpenNTF are all great, but the only reason these are used so much now is because the basic documentation is horrible.

    If you have good documentation, then all the other stuff can focus on extending xPages instead of just trying to teach us the basics.

  1. 48  Marie Scott  | 6/21/2010 8:25:52 AM

    A number of us in my office are taking the Stanford Apple Dev class. I think that this community - IBM, partners, customers, etc., can and could do a better job of putting together classes, documentation, etc. While the instructors obviously know their material, sometimes you need someone with teaching skills to teach a class, not just someone who knows the content. And I for one miss the Redbooks. There is a role for the Redwiki's, but for indepth coverage I for one want to see the Redbooks come back in the Lotus space.

  1. 49  Gary Wood  | 6/21/2010 9:36:56 AM

    The Domino Designer help file being updated so that XPages is as fully documented as LotusScript and the Formula language. That help file is the gold standard in application development help files. It is absolutely unbelievable how good that documentation is.

    This one thing will make all the difference. Videos, classes, wikis, blog post how-to's, that's all good but the Designer help file is the first place we all go and the place we all spend our time to begin learning the basics. Those other formats are where we go to learn the more exotic "tricks". Without a fully developed help file, you get what we're seeing right now.

  1. 50  Brett H  | 6/21/2010 10:55:00 AM

    Books... lots and lots of books. For XPages of course but really just anything besides "Developing Web Applications with Notes 5.0" I think that was the only dev book at the local (huge name brand chain) bookstore. Look for a dev book for oh pretty much any other development method/language/App/IDE you name it in the world and you see a sizable pile of texts. Look for ANY Notes/XPages book and well... it's really quite sad and very telling.

    Amazon search for XPages books returns... none

    Amazon search for Lotus Notes R8.x Development books returns... none

    Amazon search for ANY FREAKIN' BOOK on ANY FREAKIN' VERSION of Lotus Notes after R8 and there is one! The Upgrader's Guide (it's great but and I already have it).

    So... for current XPages OR Notes books...there's nothing out there.

    WTF? and of course WHY?

    Doesn't much look like a vendor supported platform any more...

    All the Wiki's and Help Files in the world will not help further the XPages cause if there is nothing in bookstores about it, yet there's an endless fountain of books out on competitive platforms!

    Why is that Ed?

    Why are there no (IBM commissioned or otherwise) books on R8.x? Be it Xpages, Admin, Server or client?

    There... are... no... books!

    And no-one can come back and say "Yes there is! I saw one the other day it looked very good!" Because seeing "a" book or even "a couple" of books is completely meaningless when compared to the dozens and dozens of books available for MOST other development platforms...

  1. 51  Gregg Eldred http://www.ns-tech.com/blog/geldred.nsf | 6/21/2010 1:34:10 PM

    @Brett, While not as many as other software packages, there are a few Lotus books out there. The most recent ones are published by PACKT Publishing. "Soon" there will be a Sametime book.

    Publishers will print a book if they determine that there is a market for it and that they can recoup their investment (I think that this is a very basic explanation). What the big publishers see is a lack of market/interest in this space. However, smaller, niche players may take up some of the slack.

    Writing a book is a lot of work. However, that does not preclude some enterprising person from self publishing, or taking a few blog posts and using those as a basis for a book. But if you take this route, the books will probably not appear on your local bookstore shelves nor at Amazon. They are there, but it takes effort to find them.

  1. 52  Mike Robinson http://www.invcs.com | 6/21/2010 2:03:41 PM

    I tried the wikis, and to say they are useless isn't fair. It's okay and a good effort, but there are lots of holes- far from being useless though.

    I think a lot of people look for something to the equivalent of how the notes objects are documented for LotusScript/Java. Every object, method, property, and some sort of cut and paste example. Grant it, it gets skimmy when looking towards programmable elements like outlines, framesets, etc- that's when it seemed like the doc started to be an after thought. With all the cool 8.x/8.5.x stuff it's just not there. I think I built a composite app based on one of the tutorials but had to fill in the blank. I think it worked but then was left with where to go to next.

    I'm glad you posted Declan's link as I've been looking for it and I'll start there and see if I can get started with xpages.

  1. 53  Brett H  | 6/21/2010 2:06:17 PM

    @Gregg, those are all great point's but I'd like to add a little too...

    "Soon there will be a ("a") Sametime book. Why only one? Why soon, instead of several already? Sametime is how old now?

    "A few Lotus Books out there" Why only a few? If there were a market for them, then there would be more? Well... that's pretty much a case in point. "If" there were a market out there there would be more.

    True, writing a book is a lot of work, but it seems like there are lots of other folks who don't seem to have a problem writing tons of books for other platforms...

    I shouldn't have to put in "effort" to "find" a book. If I want a book on .NET or ASP or Java or Pearl or damn near anything else on the market today "except" Notes then it's incredibly easy to find and order and receive and read.

  1. 54  Sagar  | 6/21/2010 4:07:25 PM

    @29 - IBM is doing something similar or even bigger than that but not with Lotus products See - { Link }

  1. 55  H Wilson  | 6/21/2010 5:15:12 PM

    I always thought that software documentation had two purposes. One was to show users, in this case developers using XPages, how to use the product. The second was to tell the developers OF the product, in this case the developers OF XPages, how the software was supposed to work.

    If the only documentation of software is the results of trial and error efforts to use the software, long term software stability won't exist. As new developers OF the software come on, they won't have the mental history to make sure changes are correct because there is no definition of correct.

    I have to believe that the developers OF XPages work from some formal written statements about what each XPage process is supposed to do. Bundle those statements together and you have all the documentation (not examples of course) that a developer using XPages would need.

  1. 56  Paul T. Calhoun http://www.nnsu.com | 6/21/2010 5:49:32 PM

    The issue that I'm seeing in this thread is that folks are confusing documentation with training and education.

    I see a need for both, but don't confuse the two.

    Documentation will identify and describe all of the components and properties of XPage. (The Bricks)

    This should be provided by IBM in it's entirety.

    Training will explain how you use those components to actual build something. (The building constructed using the bricks.)

    This can and is being provided by IBM and Business Partners.

    Domino Developers desperately need both.

  1. 57  Marie Scott  | 6/21/2010 5:51:37 PM

    @53 Brett - Tom Duff and I have just finished the 1st draft of a 300 page book for USERS on Sametime. I want to emphasize that it's from a user perspective - and not an admin or dev book. I was contacted by Packt Publishing last year about writing about Sametime. Publishers are going to publish what is going to make them money or at least what might fit a niche in the market. It was a concerted effort on our part, and not everyone has the time, energy or inclination to add 10-20 hours each week over many months to their already hectic schedules or when that 10-20 hours might be billable hours in a consulting position. That said, it was a great experience and we'd both take on another topic. So while it's great to say "we need more books" someone has to want to write them and publish (or self publish) them.

  1. 58  Lars Berntrop-Bos http://www.bleedyellow.com/blogs/ScriptLars | 6/21/2010 6:36:32 PM

    Re: books & documentation: Yes, sorely needed. Idea: Since XPages = JSF, get some JSF people to issue new versions of their books 'updated to include XPages'. Gives a headstart!

    Another point (here cause the other thread is closed): I would like to be able to develop in Domino Designer and administer myt servers without having to run Windows in some shape or form. Eclipse runs fine on Windows, MacOSX and Linux. Please, please, please, unshackle Domino Designer and Domino Administrator from Windows.

  1. 59  Thomas Duff http://www.duffbert.com | 6/21/2010 8:43:47 PM

    @53... I'll back up my co-author on that. Yes, we have many people in the community that *could* write books on any given topic. But the financial return is slim to non-existent for the time spent. Figure if you have 5 developers in a company of 10000 users... you may be able to sell at most 5 copies. For a publishing company to want to commit to a title, they have to see a financial return AND a way to stand out from the other titles like it. Packt has a corner on many of the Notes topics coming out right now, and I think they operate on a leaner model. Still... if you have to choose between billing at $75 an hour or getting $2K - $4K as an advance over a year of 10 to 20 hours a week? Guess what people choose...

    There are options like self-publishing, publishing on demand, etc. But again, you have to be willing to get reviewers, editors, etc. to turn out a quality product. And just because you write it doesn't mean it'll show up on shelves. Publishing is a tough business these days.

    Ideally it'd be nice for IBM to financially back a title like XPages or such, but that doesn't seem to be a path they have any inclination to follow. So, it's up to us in the community... come up with an idea, write up a pitch, and approach the publishers. They don't pull ideas from thin air. If they get pitches for Domino often enough, they'll start thinking in that area. Once they start thinking Domino, you have a chance to get a book concept approved. But just to sit and say "we want more books" gets us nowhere.

  1. 60  web design india http://www.vijayinfo.in | 6/22/2010 4:27:19 AM

    Thanks u r information

    its very useful

  1. 61  Bob Harwood  | 6/22/2010 8:37:10 AM

    Thanks to everyone for providing feedback on improving the XPages documentation. I am the Domino Designer ID lead and wanted to contribute some additional information to this thread so that people will know how our team is handling XPages documentation.

    For Release 8.5.2, we have revised the XPages user's guide in the product documentation. It now includes reference topics for all controls and properties. The overview and other material has also been redrafted. We will keep working to improve this guide.

    Our next area of focus is the scripting reference. The goal is to bring it up to LotusScript standards. This is a lot of work and will take a few revisions.

    Problems with context sensitive help (i.e., F1 help) need to be addressed. Users have complained about a lack of granularity and a lack of content. Some of these problems stem from key differences between Eclipse help and NSF help, but we cannot go back to NSF help. We will continue to work on these problems within the Eclipse framework. Similarly, we also plan to look at issues that Eclipse has created for search and indexing, with our goal being to return to more granular access to the information.

    On a non-XPages note, we are currently cleaning up the "basic" documentation, addressing hundreds of error reports and enhancement requests. This revised documentation will be available in the post-8.5.2. time frame.

    You are all also probably aware of the Notes and Domino Application Development and Composite Applications wikis. The URLs for these wikis are the following:

    * { Link }

    * { Link }

    While they do not substitute for product documentation, they are excellent information sources as well as places to share your expertise by adding or editing articles, and requesting information (for example, by using the new "Request an Article" page).

    We review comments posted here and in other Lotus-related blogs, and are making note of your ideas for improvement. If you have additional feedback to share, feel free to email us directly at lotusdoc@us.ibm.com. We will make sure to get your comments to the appropriate team member or set up a meeting to talk, if you prefer.

    Thanks again - sincerely - for this post. Most of these problems we know about from customer forums and usability testing, but a post like this puts focus on the issue and drives improvement.

    Regards,

    The Domino Designer ID team

  1. 62  Gregg Eldred http://www.ns-tech.com/blog/geldred.nsf | 6/22/2010 9:55:23 AM

    @57 and @59 - Thanks for your comments, I was hoping that you two would add to the discussion. :-) I tried, but I have no experience with actually dealing with publishers or with writing a book.

    I keep thinking back to something, I think, Rocky or Brian said about updating the Lotus Notes and Domino 6 Programming Bible

    { Link }

    "Never again." Great book, no doubt, however the work required for something like this is . . . daunting.

  1. 63  Brett H  | 6/22/2010 10:50:11 AM

    Sorry to bend the thread into this direction Ed, but I feel it's critical to get material out and available to new and existing developers if you expect them to take it up.

    Gregg and Marie, that's great news! I'll look out for it.

    If a student (or anyone!) has actually managed to download a free copy of Designer and now wants to learn more, he/she goes to the local or online bookstore to look for "Reference Guides" or "Bibles" or "Secrets of XPages Development" and sees nothing at all...

    "Hmmm... why are there no books on this stuff?" He thinks, then looks at the 35 different .NET or whatever books. What decision is he faced with?

    @59 Maybe it's because Notes centered authors are all too busy working to write books, because unless it's that, then all the other IT book authors must be out of work and desperate, because there sure seems to be a bunch of IT authors out there that are publishing. If the publishers only publish what they think will make money then I wonder why they think that they won't make money off of Notes/Domino/XPages books?

    Perhaps it's market perception? damn, I said the "m" word...

  1. 64  Thomas Duff http://www.duffbert.com | 6/22/2010 12:03:52 PM

    To give you an idea of time... Marie and I started in November, with each chapter basically scheduled for two weeks (a little more time was included for Christmas and Lotusphere). We finished three weeks early for our end-of-June deadline for first drafts. We now have to turn around and incorporate 2nd draft items, one chapter every four days until we get all those done. We *hope* the writing will be done at that point.

    But while we're doing this, we have day jobs...

    You do have a lot of authors... and many of them have done this once and decided that's enough for them. There are full-time writers and speakers out there, but they are few and far between. If you got a $5K advance to write a 500 page book, it's likely that the $5K would be ALL you would see for your effort. You could be lucky and have sales go wild. But reality says differently.

    There's a saying among book writers... You live on your advances, and you vacation on your royalties.

    I don't think book writers take very many or very extravagant vacations any more.

  1. 65  Brett H  | 6/23/2010 10:14:55 AM

    Can/does IBM subsidize authors to write books?

  1. 66  Mike VandeVelde http://www.cascadiacodeworks.ca/ | 6/23/2010 11:21:06 AM

    Take the help that is in DDE, and duplicate it in the wiki. For each help document in DDE, include a link to the corresponding entry in the wiki. Lock down the wiki entries for editing, but allow comments. Then you get things like:

    "Fix this part, it's wrong" - fix that part (and hide the comment?)

    "Here is a blog post related to this" - maybe approach the author about including some of their code as an official example?

    "But I'm trying to do [this], and this help just doesn't help because it doesn't explain [this]!" - expand the help (and hide the comment?)

    "I haven't read anything anywhere, but can someone just tell me exactly how to do my job?" - hide the comment ;-)

    I talk about hiding comments, because you want the meat, maybe only hide so that you can browse the fluff if you really want to. Moderating might not be fun, but it could be very useful.

    So you get evolving and expanding help, with comments pointing to further reading. Instead of IBM paying people to write help, IBM pays people to be editors in the wiki and good help emerges from the community. If the official help entry gets updated in the wiki because of user comments, that update gets included in the next release of DDE. Still a wiki (as opposed to just blog style comments) so that you could possibly promote knowledgeable community members to editors, maybe of restricted subsections, or something like that. Something for people to aspire to, a badge of honour?

    Developers go to the included help first, and if that doesn't give them what they need then they have an official link to a central location that organizes the wider universe of help that is available out there, currently mainly through Google.

    The wiki is nice, this would drive traffic to it and make it explode, it would become the new forum. The 8.5 forum does not seem very active? At least not as active previous ones.

    Sort of like this:

    { Link }

    For example:

    { Link }

  1. 67  Thomas Duff http://www.duffbert.com | 6/23/2010 11:49:48 AM

    Not that I'm aware of...

  1. 68  Mike Woolsey  | 6/24/2010 10:06:08 PM

    First off -- I love XPages. I love many of the features others don't particularly like, even.

    But yeah, the documentation really leaves a lot to be desired.

    Is there any documentation of Expression Language -- allowable syntax, what you can do and what you can't?

    Any documentation on where expressions can be used? I've tried slapping them inline to try to translate some things on the fly, and that clearly doesn't work. They appear to work only within certain tags.

    And man, how do you manage to get the XPage editor to stop trying to reformat your content? I have some Javascript that I need to execute, and about every fifth edit the XPage editor gets in there and word-wraps my code at strategic points, making it nonsense.

    So yeah -- more documentation, more detail on how you can manage to introduce Javascript into onLoad (even through XSP.addOnLoad() or dojo.addOnLoad()). I mean -- this stuff is still in ND7.

    There's plenty more to deal with. I have dozens of processes that need to go through WebQueryOpen agents, and after a series of scans through Designer I just figured this was forgotten.

    Finally -- no matter how nice XPages are -- and believe me, they're nice -- so far the form features aren't quite "there". Pass down through the header, body, onload, keyboard intercept features on a form: and help the Javascript-savvy users get there. What do we do in an onLoad event? Why, setting initial focus. That takes about three or four interesting "aha!" discoveries of functions that aren't in the documentation to pull it off, as far as I can tell. How about the JSHeader? pulling in keyboard handlers -- I've got no idea. But then, maybe that's covered by the controls.

    WebQueryOpen events? Mostly I use it to integrate with other data sources, creating & saving & reopening DECS retrieval documents, then copying data into an in-memory document, and displaying that.

    How do you get an XPage to work smoothly with dojo? I've been using some dojo dijits (in preference to the integrated datepicker) -- but they "redraw" many of the controls after the page is rendered. I'd love to make this smooth.

    How do you validate data that may or may not be rendered on your XPage, currently? I've always liked Notes' "loose until saved" method of validation, and so that has factored into my validation schemes in a big way. Even now I'm simply annoyed by websites that won't let me loose from an input or a page until everything's done. My thoughts going through this step-by-step junque -- "(page1) I just want to see what else you're going to ask -- (page2) this is frustrating -- how many pages are there? -- (page3) I know how to get out of this." We make it easier. We've been trained that way in Notes. Help us do the same in XPages.

    Xpages have really useful features. I wish the features could be applied more simply, 1-to-1 with the forms we've got. We need them integrated with many of the backend features we already have with forms. We have admittedly done a whole lot with simpler data mapping. The cost of redoing mapping into an XPage tends to increase the work we do. And that means less rapid development. And less competitive development.

  1. 69  Gerald Mengisen  | 6/26/2010 4:10:06 PM

    When the time came to write a real-life application in XPages, using the XPages framework { Link } was a huge time saver (once I figured out how to plug in my own content).

    After that, Julian Buss' XPages wiki { Link } was my primary source of tips, followed by Google.

  1. 70  Scott Good http://www.teamsol.com | 6/28/2010 3:22:53 PM

    Sorry...late to the party. Add one more vote for LotusScript-like documentation with cross references so you can find alternative approaches. Also, real-live examples so you can actually see how somebody who understands whatever it is I'm trying to look up is actually supposed to be used.

    I have to assume that there have been hundreds--probably thousands--of hours of meetings and documentation of exactly which methods and properties and options and components and...all that...were going to go into the shipping product. Sure all of this wasn't just "you guys all go write some stuff and we'll put it into the box." So...isn't there also hundreds or even thousands of hours worth of documentation used to tell the developers what to write and how it should work and what it's used for? Surely that would be a great help in moving this whole thing forward. It's not like we're starting with a completely blank slate (I hope).

    Add a vote for videos, particularly of conceptual information, but also of how-to-do-its. I agree with others who say videos are not documentation but, as somebody who has written an inordinate number of magazine articles on Notes/Domino technologies, I can tell you I would much rather see someone actually SHOW me and TELL me how something works than to have to read it. I want to be able to look up and read code examples (i.e., documentation) but I'd rather have a demo of techniques.

    Finally, I don't want to have to wait until sometime in "the post 8.5.2 time frame" to get a start at real documentation. Can we have what's done now, NOW, please? Dribbling it out a little bit at a time, even if it's imperfect, is better than keeping it all secret until it's all shiny and complete. There are people out here trying to get work done...

    (Thanks for asking).