Improving the overall "out-of-the-box" experience #199
Comments
|
Backtracking a bit in the newcomer's journey:
The Jive documentation might be a good role model for some of this. |
|
I also think redoubling the efforts on simplifying the default pom.xml that the archetypes generate is critically important, as that's one of the first places developers will look (especially experienced Maven developers) if things go wrong. Last time I used the archetypes (about 6 months ago) I got a pom.xml that contained a bunch of "advanced" switches and options that could (and should) have been defaulted in the parent pom, and that more than tripled the size of my pom.xml compared to the prior one I'd been using (which used cough the maven-amp-plugin cough). While I get the need to support advanced / expert use cases via configuration switches, that stuff must be hidden by default to protect / support the newcomer. It can then be documented for the expert if need be (although in all likelihood they'll have cracked open the parent pom and, ideally with support from inline comments, have figured it out for themselves anyway). |
|
I agree with @pmonks on simplifying archetype's pom.xml: any of the Most of the questions I see here are answered by docs.alfresco.com, but maybe there isn't a place where they're all listed; wdyt of an FAQ section (or more than one?) Few questions before we start on this issue:
I'll make sure this content is also part of the Training module. |
|
To augment @maoo answer and to the points of @pmonks (btw wondering, @pmonks, were you aware of the extensive tutorials in the official docs.alfresco.com?), it would be good to understand what you see missing in the official (supported) docs and extensive tutorials (which BTW need update for the 2.x release of the SDK):
@pmonks would love your feedback! |
As reported in MNT-12050 those docs are inaccurate. They are also ambiguous, in that they say two contradictory things:
That docs page also don't link to the relevant download pages, leaving newcomers to their own devices to find the right way to obtain the pre-requisites.
Those were examples (hence the "TBD" at the end). We should think carefully about what components we recommend (you seem to agree that Eclipse is one such recommendation) and make sure they're described (including versions, download links, etc.). I note that m2e is recommended, but there's no mention of how to obtain it.
Agreed.
Agreed.
Disagree. That page is currently a pro-active "here's how you should configure" Maven description. What I'm referring to is a reactive "now that I think I'm done, how do I validate what I've done?" type of material. As an aside, this page is a nice demonstration of another problem with the docs - they're broken up across too many pages, making it more difficult for a newcomer to simply follow a single script without having to click or navigate around (with the associated risks of losing their way). I would again point you to the Jive Documentation as a better way to lay this out. The page is very long, but it provides a single, linear path for the newcomer to work through, without having to click around or lose their way in the docs site's navigation tree.
What about developers who aren't using the Enterprise artifacts? Do they need to do anything? Should they remove previous Alfresco settings from ~/.m2/settings.xml that they may have from maven-amp-plugin (or earlier!) days? What if they're working on both maven-amp-plugin and Alfresco Maven SDK projects? Are we saying they must migrate their maven-amp-plugin project, and if so can we have material (a tutorial, perhaps?) that shows how to perform that migration?
A useful page, but again too fragmented. This should be part of a general "pre-requisities" section of an all-in-one document.
While valuable, all of those tutorials assume a valid, functioning installation of Java, Maven, the Alfresco Maven SDK, etc. What I'm talking about is material that allows the newcomer to validate their installation before embarking on any of these tutorials. I personally don't believe the tutorial format is appropriate for this kind of validation process - I'd prefer to see it as simply a well-defined linear list of "do this, and check that the result is that" type steps, ideally again as part of a single, large "installation & configuration" page (i.e. at the end, after they've run through all the installation & configuration steps). |
|
I will be doing a thorough review / update for the 5.0 docs. If you think it would help we can have a longer tutorial near the beginning that takes people through setting up the pre-requisites. I will take a note of the other feedback and incorporate where sensible to do so. Thanks! |
|
One possibility for easier usage that springs to mind. Perhaps the "Choose archetype" menu that is displayed on the command line after you type mvn archetype:generate could be simplified to display only the most essential information, the name of the archetype perhaps? I always have trouble scanning through the mass of information for just the name of the archetype I want to generate. |
|
The biggest issue we have had, not as newcomers per se, but nonetheless as part of the "out of box" experience, is the lack of a solid/supported hot-swapping solution for Java development. Before we switched to Java 8 we were using spring-loaded, but it chokes on Java 8 code like lambdas and its development seems to have completely stalled. And while it's awesome and essential that JRebel support is being worked on, there are plenty of organizations that aren't ready to pay for JRebel and/or prefer an open-source solution. We have had decent success with HotSwap Agent in combination with DCEVM, although it could be a lot better, as there is no support for hot-reloading in XML-based Spring contexts. There is in fact a plugin for Spring, but it doesn't grok the XML context definitions - so we have to manually specify search paths where it should look for file changes, and completely restart the instance if anything within the context XMLs changes, which is a pain. None of the current options for hot-reloading are ideal. Java development without hot-reloading is pure masochism, JRebel has too steep a price especially for users of Community, and forcing users to hack together a custom HotSwap Agent setup is exactly the kind of thing the SDK is supposed to avoid. If Alfresco were to commit to officially supporting a project like HotSwap Agent it would help a lot with replacing the now-defunct spring-loaded. |
|
@mischkl, SDK3 offers support for Hotswap agent with a sensible default hotswap agent that picks up the essential changes. I do agree that hot reloading is an essential feature, but we are bound by the constraints of 3rd party tooling for this. Spring Loaded doesn't seem to be a viable option anymore. JRebel provides a superb hot reloading experience, but comes with a price tag. Hotswap agent does the basics with the exception of reloading beans. Hotswap agent does have a neat plugin structure so this could be possible in the future. Overall I think the SDK3 offers a much better out of the box experience. I will close this issue and we can open new issues for individual improvements once the release is out. |
|
@ohej That's awesome news!! Thanks to the team for all the hard work in getting Hotswap agent integrated into the SDK! |
@mindthegab mentioned we should focus on having the best possible "out-of-the-box" experience with the SDK.
Right now I'm trying to gather the most asked questions/issues from IRC and the forums, this should give us some idea about the areas that could be improved.
We can probably not expect to fix these issues within the SDK, but rather improving the documentation, adding howto's, guides etc.
Please feel free to add the problems you've encountered or tried to help/answer the most.
Overall areas/observations:
The text was updated successfully, but these errors were encountered: