Marcel-

Thanks for the feedback.  I'll make sure the HowTos start more basic.  However, people don't need  IT backgrounds to understand relevance or equations.  This is all basic stuff for people doing surveys.  Regardless, I'll make sure there are basic, intermediate, and advanced examples to cover the needs of our user base.

Since it may be a while before a GUI can be developed, I'll also show examples and screen-shots of what syntax errors look like and how easily and quickly they can be fixed.
Since my screenshots are from real surveys, I'll also export the .lsg files, and make them available, plus make the whole  survey with all the examples available.

Since I'm not using SGQA codes, there is no problem with importing surveys - they'll always work unless the person is overlaying existing question codes.

Your last comment is important, and I'll highlight that in the documentation too.  For EM to fully work as expected, people should use unique question codes. I expect that anyone doing serious analysis of their data is already using unique codes, since it is the code value that becomes the variable name in SPSS and R exports.  It is possible to do all of the EM functionality using SGQA codes, but I'd advise against it since the SGQA codes won't be changed on import (at least not using the current code).

So, rather, I'd advise people to use unique question codes.  We should also add a check to tell people if they try to re-use a code (e.g. a pop-up when they save the question, plus a check when they try to activate the survey).

This does raise the issue of whether people can easily import the same group multiple times to support virtual "looping" of a group of questions.  Since EM does internally use the SGQA codes, it will still be possible to import the same lsg group file multiple times.  However, in order to get the expected behavior, the user should change all of the question codes and make sure that the relevance and tailoring equations use the new code.  The way I've always done that in the past is to simply add an iteration suffix to the questions. But, it also ties back to my hope that we can create an Excel import format so that it is easier to create 1000+ questions with lots of repeating content (like large blocks with similar relevance, or repeating groups) - see this isssue:  http://bugs.limesurvey.org/view.php?id=5105

/Tom




On Thu, Sep 22, 2011 at 4:45 PM, Marcel Minke (Limesurvey) <marcel.minke@limesurvey.org> wrote:
Hi Tom,

thanks a lot for this documentation. I think it is a good first start but please take care to not write documentation from the developer point of view but from the user point of view. My experience from years of support is that 90% of the users do not have any IT background knowledge so they need really simple examples for each possible use case. Some really simple stuff for the most common use cases where they only need to replace one value is something they can deal with but complex operations will give them a headache.

So how can we deal with this? Some suggestions:
1. We need a user friendly GUI, something like the condition designer but even nicer :-)
2. How about creating a wiki page where users can share their EM examples? We have something similar for regular expressions (http://docs.limesurvey.org/Using+regular+expressions&structure=English+Instructions+for+LimeSurvey) and this list grows.
3. Referring to #2, maybe we can have some Google Code In 2011 tasks to create further simple use cases?!
4. Since we can sum up most examples within one question group we should offer some sample .LSG files for each example so users can simply import it to play around with it and change some values for testing. We did something similar for complex question types and these files are downloaded a lot.

Two short questions:
1. When importing a survey which uses EM expressions, will there be any problems with certain IDs which have to be adjusted?
2. I might simply not have understood it correctly, but what happens if I use the same question codes for each question at the assessment examples (http://docs.limesurvey.org/Expression+Manager+HowTos#Calculation_Assessment_Examples)?
Wouldn't that cause problems?
In the future, will we need a check that each question code processed by EM is unique?

Greetings from someone who hates writing documentation...
Marcel




Am 22.09.2011 20:38, schrieb Thomas White, MD, MS, MA:
Marcel, Thibault and  Carsten-

Is this the level of detail you think would be helpful to survey authors trying to learn to use EM to create surveys? -- http://docs.limesurvey.org/Expression+Manager+HowTos

Lots more to do, but this is a representative start.

/Tom

On Thu, Sep 22, 2011 at 5:21 AM, Marcel Minke (Limesurvey) <marcel.minke@limesurvey.org> wrote:
Hi Tom,

thanks for documenting your great feature so well, that really helps.

At the forum I have seen several posts like "With the new Expression Manager you can solve your problem this way or that way.". Regarding your question for which additional information we might need I would like to ask for a documentation section with some use cases. There are several issues at which EM can be used in the future so having a small use case, just a simple step-by-step explanation how to set it up for each case, will help a lot to understand the various situations at which EM could be used.

Some possible use cases from memory:

1. Calculate assessment values at runtime and store the results at the survey data

2. Replace conditions (we might need 2-3 use cases for different conditions of different complexity)

3. Replace text strings based on certain values like "Dear {Mr}/{Mrs} Smith..."

4. Show a summary of the user's answers at the end of the survey

...

For a first and general understanding of EM I consider this quite useful and a good first start to play around with it. Once this is done we could spread the word on limesurvey.org (like for the CPDB feature: http://www.limesurvey.org/en/component/content/article/1-general-news/226-new-qcentral-participants-databaseq-feature-is-ready-for-testing) and at the forum.

The combination of use cases and some testing instructions might help to get more users on board. What do others think?

Best regards,
Marcel

Am 22.09.2011 01:29, schrieb Thomas White, MD, MS, MA:
Carsten, Thibault and others-

As discussed in yesterday's developer meeting, the core documentation for EM is now complete here:  http://docs.limesurvey.org/Expression+Manager+for+Developers
You should also read http://docs.limesurvey.org/Expression+Manager for additional details and nuances.

Please let me know if there are other categories of information you'd like me to add.

/Tom
------------------------------------------------------------------------------ All the data continuously generated in your IT infrastructure contains a definitive record of customers, application performance, security threats, fraudulent activity and more. Splunk takes this data and makes sense of it. Business sense. IT sense. Common sense. http://p.sf.net/sfu/splunk-d2dcopy1
_______________________________________________ limesurvey-developers mailing list limesurvey-developers@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/limesurvey-developers

------------------------------------------------------------------------------
All the data continuously generated in your IT infrastructure contains a
definitive record of customers, application performance, security
threats, fraudulent activity and more. Splunk takes this data and makes
sense of it. Business sense. IT sense. Common sense.
http://p.sf.net/sfu/splunk-d2dcopy1
_______________________________________________
limesurvey-developers mailing list
limesurvey-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/limesurvey-developers


------------------------------------------------------------------------------ All the data continuously generated in your IT infrastructure contains a definitive record of customers, application performance, security threats, fraudulent activity and more. Splunk takes this data and makes sense of it. Business sense. IT sense. Common sense. http://p.sf.net/sfu/splunk-d2dcopy1
_______________________________________________ limesurvey-developers mailing list limesurvey-developers@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/limesurvey-developers

------------------------------------------------------------------------------
All the data continuously generated in your IT infrastructure contains a
definitive record of customers, application performance, security
threats, fraudulent activity and more. Splunk takes this data and makes
sense of it. Business sense. IT sense. Common sense.
http://p.sf.net/sfu/splunk-d2dcopy1
_______________________________________________
limesurvey-developers mailing list
limesurvey-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/limesurvey-developers