Bug 869999 - Getting Started with Errai and CDI documentation issues
Getting Started with Errai and CDI documentation issues
Status: CLOSED CURRENTRELEASE
Product: JBoss Enterprise WFK Platform 2
Classification: JBoss
Component: Documentation (Show other bugs)
2.1.0
Unspecified Unspecified
medium Severity medium
: GA
: 2.3.0
Assigned To: Petr Penicka
Matous Jobanek
:
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2012-10-25 06:16 EDT by Tomas Repel
Modified: 2014-01-13 03:40 EST (History)
3 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2013-07-16 07:33:45 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Tomas Repel 2012-10-25 06:16:18 EDT
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.
Comment 1 Isaac Rooskov 2012-10-29 19:47:43 EDT
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.
Comment 2 Jonathan Fuerth 2013-03-04 16:31:48 EST
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.
Comment 3 Petr Penicka 2013-03-15 07:42:21 EDT
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.
Comment 4 Jonathan Fuerth 2013-03-15 10:08:04 EDT
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!
Comment 5 Karel Piwko 2013-04-19 07:30:40 EDT
Marking as RN not required.
Comment 6 Petr Penicka 2013-06-14 06:23:46 EDT
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 [1]. I did quite a lot of edits compared to the original community text, any comments or discussion related to these more than welcome.

[1] https://documentation-devel.engineering.redhat.com/docs/en-US/Red_Hat_JBoss_Web_Framework_Kit/2.3/html-single/Errai_Quickstart_Guide/index.html
Comment 7 Jonathan Fuerth 2013-06-14 17:30:15 EDT
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.
Comment 9 Petr Penicka 2013-07-02 05:56:23 EDT
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.
Comment 11 Petr Penicka 2013-07-02 10:56:04 EDT
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.
Comment 12 Matous Jobanek 2013-07-03 09:31:30 EDT
Verified in WFK 2.3.0.CR2

Note You need to log in before you can comment on or make changes to this bug.