Red Hat Bugzilla – Bug 869999
Getting Started with Errai and CDI documentation issues
Last modified: 2014-01-13 03:40:36 EST
My notes on Getting Started with Errai and CDI doc:
Chapter 1 Technology Primer
- 1st paragraph, two times 'upon' in sentence
1.2. Contexts and Dependency Injection (CDI)
- typo, 'thee' instead of 'the' in the 3rd paragraph
Chapter 2. Create your Project
- Maven Required border - the 'install Maven' link is not valid
- latest archetype version is 2.1.1.Final
3.2. Importing your project
- step 10: there should be explicitly mentioned that the checkbox "Launch and deploy from this directory" has to be toggled on, it is only visibe on screenshot
Chapter 4. A Gentle Introduction to CDI
- it seems a bit unfinished to me. The very first paragraph (in yellow border) says that the example created in previous sections is the basis for this chapter, but in reality the section just covers some general introduction to CDI with no direct relation to the example.
I'm changing the version to 'unspecified' for now as this book will not be released for WFK 2.1 now since the community has informed me it is not ready for productization.
We are now aiming to publish this book with a future WFK release.
In response to Tomas' review:
> Chapter 1 Technology Primer
> - 1st paragraph, two times 'upon' in sentence
This seems to have been fixed already.
> 1.2. Contexts and Dependency Injection (CDI)
> - typo, 'thee' instead of 'the' in the 3rd paragraph
This also seems to have been fixed already.
> Chapter 2. Create your Project
> - Maven Required border - the 'install Maven' link is not valid
> - latest archetype version is 2.1.1.Final
I tried the 'install Maven' link, and it took me to http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html, which does exist. This may also have been fixed in the community doc already.
I updated the version to 2.2.0.Final
> 3.2. Importing your project
> - step 10: there should be explicitly mentioned that the checkbox "Launch and deploy from this directory" has to be toggled on, it is only visibe on screenshot
Added this instruction; thanks.
> Chapter 4. A Gentle Introduction to CDI
> - it seems a bit unfinished to me. The very first paragraph (in yellow border) says that the example created in previous sections is the basis for this chapter, but in reality the section just covers some general introduction to CDI with no direct relation to the example.
I just talked to Mike about this. He suggests leaving out the 'Gentle Introduction to CDI' section, and removing the references to it from within the preceding sections.
Jonathan, thanks for handling these in the upstream docs.
I'm afraid we don't have the resources to productize this guide at the moment. There are a number of Windows 7 Aero screenshots with waterfalls in the background that are a no-go for enterprise docs. We will have to retake them, and do some other edits.
As the requirement to productize this guide is not part of the release plan for WFK 2.2, I'm shifting this to WFK 2.3. I'll make sure to handle the docs work myself in the next release.
Thanks, Petr. I'm really looking forward to working with you and hearing your insights on this and the other Errai documentation.
Regarding the Windows 7 screenshots: we did that on purpose, at great inconvenience to ourselves, because we've been told that the typical WFK user is overwhelmingly likely to be on Windows, and we wanted to make this "walkthrough" style guide as familiar as possible to the target audience. Sorry to hear this has made your job harder as well!
Marking as RN not required.
Jonathan, I finally found the time to get this done. After removing the "Gentle Introduction to CDI" as mentioned in Comment 2, and also removing m2e plugin installation as JBDS contains it by default, only the Technology Primer and Project Import to JBDS remained.
This is not CDI specific, so I did not create a whole new guide, but instead merged it with the current Errai Quickstart guide.
Ready for review at . I did quite a lot of edits compared to the original community text, any comments or discussion related to these more than welcome.
Thanks so much Petr. The overhauled Technology Primer section reads really well, and works nicely as an introduction to the quickstart guide.
The new screen shots in the tooling walkthrough look great too.
My only question/comment/critique is about the boilerplate in the introduction. The following trademark acknowledgements are out of place in an Errai guide: Linux, XFS, MySQL, Node.js. Is there any way to remove these? Obviously this is a very minor issue. Just curious.
Hi Jonathan, thanks for the kind words.
As for the legal notice, I have just confirmed with my manager that it needs to be uniform across all Red Hat books. The same legal notice appears even in docs for RHEL, RHEV, etc., and customizing it is not allowed.
It's open source, my pleasure if you take it and reuse it :) If you want the DocBook sources, please ping me or drop me an e-mail, I'll direct you to them.
Verified in WFK 2.3.0.CR2