The only explanation there is for a new user is on the Create your own AWM homepage:
" Create collaborative web applications within minutes, based on XWiki’s powerful structured data management system."
Improvement
This previous sentence is a bit vague and also has a marketish tone without providing more answers to the questions of the user.
We could improve it and rewrite it as:
Create collaborative web applications. Define the kind of data that will be used and presented to your users. You can also set an icon and a description for your app. Learn more.
What do you think?
What would you modify?
Is there anything else you’d include? Note that we shouldn’t make it too long as to not intimidate people with the level of new info.
I first thought this proposal about AWM doucmentation and extension code. Well, for me, there’s no difference as I checked before using the official documentation. But for new users, having a direct link on the documentation page of AWM will be useful. My only suggestion is to wrap it into Info box macro.
Hi Adina, thank you for taking a look at this. I agree with you that the original opening can be improved, and I like the proposal as I feel it summarizes AWM for the general users.
Linking to the online documentation is a nice touch as well. Just one thing about this is that some users might be behind a firewall and unable to access it, but I don’t think there’s much we can do about it.
I understand the rationale and why it seems like a good idea but I’m more towards -1 for the following reasons:
If we feel the need to have a link to the doc, it means we’re putting a bandage on a badly designed feature that is not easy-enough to use. I would prefer that we spend time to simplify its usage.
If we want to start linking features to documentation then I’d prefer we do it in a more generic way, like having some qestion mark icon in the content menu or elsewhere. I see no reason to link to the doc for this feature and not for the 1000s others we have in XS and in all extensions. In addition this would remove the need to add some text sentence which requires translations in all languages (and which will be seen as a bug in all languages not having a translation for it yet).
If we want to link to some doc page then this create some constraint since it means we need to be very careful to not rename/move the page forever (since it would break old versions of XWiki in the future if we do so). Thus we’ll need to create a fake URL and map it to a current page and then we need to maintain this mapping. The more URLs we add the harder to manage it.
We have a Help app bundled in XS and I think it might make more sense that each extension could contribute some help pages for the Help app and then have the question mark icon I mentioned above link to that doc page. This doc page could have local doc or link to external doc. At least that would centralize all help for XS in a single place. But IMO, it’s even better to not need any doc, see point 1) above.
Last, while this could potentially help some newcomer, it’s useful only once and once you know how to do something it’s just painful to see the message all the time… Thus it’s better if it’s hidden behind a question mark icon for example. In addition, you’re going to make it painful for the 100,000+ current users who already know ho to use that feature…
Here to talk about another small improvement related to App Within Minutes (AWM)