XPO documentation - what do you need?

What I feel is lacking in XPO's documentation are best practices on the use of their framework.  The examples are fairly good but they don't provide enough detail to really use this framework at a professional level and to produce a professional level application.  Better consolidation of the documentation would definitely be helpful as well.  Sometimes, the answer I'm looking for is available; it just takes awhile to search for it in the various sources of hints and tips.

It's great to see you taking initiative on improving XPO docs.  I see at least three ways of nailing this.

1. Add some wiki-like ability to your online documentation.  Allow users to upload comments, annotations, additional examples, and sample projects.  Moderate the content to ensure accuracy and quality.  Let your users contribute and incorporate the better pieces into the official docs.

2. Run some polls and questionaires on your website for customers: score the doc areas that are most helpful.  Least helpful.  What's missing?  Allow users  to submit structured information about what they were looking for, what they found on it, where they expected to find the answer in the docs, or what they were confused by.  Your support center for submitting bugs and feature requests is excellent; I use this all the time and get to track where these issues are at.  Or like you said, using the existing Bug Report or Feature Request system may do the trick.

3. Discovering the right set of topics, the right depth of content, and helpful categorizations and pointers, could be accomplished successfully by creating a reference solution, similar to Microsoft's Fabrikam solution, and involving DevExpress customers (especially new-comers).  Something that's simple enough to build relatively quickly, but covering enough scenerios to realistically represent the full gamut of problems to solve.  It would involve a website with master-detail grids, generated data in the hundreds of thousands of rows instead of 20 rows, and other real-life situations.  Implementing a series of realistic use cases would not only bring attention to missing areas of supporting documentation, but also of badly-needed functionality, to make new things impossible, as well as making existing functionality more intuitive.

The usability testing would obviously be more expensive, but you could easily combine XPO, windows forms controls, web controls, etc., all into the same reference app, and present it as proof that XPO works well in large-scale, distributed systems.

From my view, it is about creating and managing a documentation database that would greatly assist in automating the forever ongoing management of documentation. It seems that everyone is accustomed to the convenience of Xml comments because it seems so logical to create documentation "on-the-fly". How could documentation be more convenient?

What gets exposed as a weakness over time is that documentaion is version specific and that support center answers are not required to be linked to these Xml comments. (its not a database - but could be). The biggest problem I have with the knowledge base is that many solutions are based on old versions and I have to sort my way through the spider-web of what is current and what is not.

I would recommend a database structure to be developed that would ID documentation based on namespace, membership in that namspace, and according to version number. When support staff answer questions, they should be required to link the answer to the appropriate namespace versioned record.

Thus, I could go online where the documenation is made available and drill into a member of a namspace, and it would there that I find the links to support center issues for the version I am drilling into. If I don't find what I need, I can step back in versions. I could also look at all support center answers related to that namespace member regardless of version, but it would be clear what version each issue was related to.

Furthermore, each issue in the actual documentation should be "flagged" when it is known to be less preferable or outdated. For example, the "typeof" Xpo examples should be flagged as somehow not preferable to using the generic version. I would expect that these flags would trigger developers to move away from the older methods because they will potentially be "obsolete". If the database has answers from the support center maintained by version, then only the "actual" documentation would HAVE to be modified with version upgrades because the daily responses provided by the support center would already be linked directly to a version.

I compare the documentation issue with OOP concepts in general, if something is updated in one-spot, it should automatically propagate itself everywhere else or redundency occurs which increases overhead in maintenance and opens the door for "out-of-sync" problems (the issue corrected in one spot, but not elsewhere). I see this happening greatly with documentation. I have to check the documentation, the support center, the knowledge base, etc because they are not synchronized.

.. just a suggestion or possible solution.

Trevor

The problem with XPO is that it's simple enough to understand but complex to master as it is at the crossroad of many technologies.
I like Dan's suggestion of using a wiki and allowing feedback directly where you look for: MySQL has had user feedback on every single page of its very extensive online documentation for years and most often than not, a particular issue is solved by searching for that page then reading the user comments.
A wiki takes this a step further and would allow us to post example code and projects.

I believe that showing how XPO can be used in a variety of typical real-life situations would be extremely helpful as a starting point for newcomers: looking at the requests from the newsgroups, there are a few common scenarios that come up regularly:
- multi-user access, n-tier and disconnected applications
- use in the compact framework
- data validation and business rule enforcement, including reporting errors back to the UI
- undo/redo

Of course, each of these topics have many solutions and most of them are not XPO-specific, but so far DevEx has had a mostly hands-off approach to the issues (the one that cracks me up is the bit about data validation in the doc. Seems that DevEx didn't want to open that can of worm...)

Nevertheless, I believe that these topics need to be addressed: a lot of people (me included) may have limited experience in database systems and ORM. What we're looking for are starting points to get us going in the right direction and show how XPO may be used in a particular context that we can re-use to solve our particular problems.
It wouldn't mean that any particular solution may be the 'only' or 'definitive' one, just that they implement it in a way that will work and do the job well.
Other users can contribute and suggest other ways, but at least these sample projects would act as catalysts to get the 'XPO reaction' going.

In the end, XPO is great and powerful but it tends to suck a lot of time as trying to use it in non-trivial projects requires a fair amount of under-the-hood knowledge that is missing from the doc.
Reading the source code isn't made easy by its lack of comments and any general technical overview (although it's still very useful and I commend DevEx for making it available).
Trevor is also right in pointing that as time goes by and outdated information still has the same likelihood of showing up in searches as the newer more relevant one, it becomes harder to get to the important stuff quickly and not get side-tracked.

Anyway, thanks for asking for our feedback :-)

Renaud

Examples of how to use web services (converting objects to/from xml)

I like Trevor's idea a lot.  I think he's onto something.  In addition, it would be cool to see some kind of trackback feature, where support center issues that link to the current piece of documentation would be listed somewhere in the documentation.  Questions that get answered, or bugs filed in regard to a help topic, would be accessible from the help topic.  That way, after reviewing the "official" documentation, you could easily start reading through all of the on-going activity concerning that topic.  These links could be removed once the content they point to is integrated into that help topic.

+1 on all suggestions here.

Dennis let us know that the DX wiki is in the works.  This will really help.

More code examples.  XAF has lots of examples.  XPO could definately use more examples.  

There needs to be clarity on exactly how the XPO documentation applies to XAF's use of the ObjectSpace with Views.  There are two perpectives on XPO:  

1) Stand alone

2) Within XAF and XAFML.

An ObjectSpace Session property is really a Unit of Work, correct?

Have you considered expanding the scope of the ObjectSpace to include it as part of XPO?  I find the ObjectSpace very handy in managing a related set of BOs.  

BTW:  I'm really looking forward to the upcomming XPO Interfaces and dynamic BO class support.

All good work, thank you.