[jbosstools-issues] [JBoss JIRA] (TOOLSDOC-378) Documentation on adding EAP to JBDS 7 is not as effective as documentation for JBDS 6

Wed Jul 24 20:59:26 EDT 2013

    [ https://issues.jboss.org/browse/TOOLSDOC-378?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12792822#comment-12792822 ] 

Michelle Murray commented on TOOLSDOC-378:
------------------------------------------

Thanks for your feedback [~nickboldt]. In summary, I have extracted your main points as:
1) There aren't screen shots, so no specific examples
2) The html anchor and section title don't match
3) The content differs between the 6.0 GSG and the 7.0 GSG & Install Guide, with a negative impact on users

In response:
1) =
Screen shots are to be added to all docs asap after GA, hence introducing examples. I am working on the Install Guide this week.

2) =
The mismatch in the html anchor and section title occurs because I created the section (and hence file (auto-process)) with one title and then later changed the section title (but the file name didn't change (again auto-process)). While I can see that having matching is best for new users, I wonder what is best for returning users? If someone has bookmarked a link and subsequently I change the section title (e.g., due to a typo or superficial UI item rename) and this were to cause the file name to change then the user's link would break. Which is worse from a user's perspective? Mismatched names or broken links? This is open for debate so please feel free to continue this discussion.

3)  =
6.0 GSG has 'Adding and configuring a JBoss server runtime'* 
7.0 GSG has 'Set up a server using runtime detection'
7.0 Install Guide has 'Set up runtime detection'
7.0 User Guide has sections for 'Define a local server with runtime detection', 'create an additional server runtime environment', 'define an additional local server'*

The two * sections contain the same content (minus missing screenshots and more info about the fields of the wizard that the user has to complete).

I would argue that:
* The section in 6.0 GSG is incomplete and so flawed; it assumes the user made use of the optional runtime detection setup during installation so has runtimes available for which to make servers. 
* The section in 7.0 GSG is sufficient for the aim of the guide, namely walking a user through the introduction of the ticketmonster example. It ensures that users can install and create a server using the simplest approach and the one we want to promote = runtime detection.
* The section in 7.0 Install guide is sufficient for the aim of the guide, namely installing JBDS. In the future this guide will be extended to have a few testing procedures for users to check that things are set up correctly, such as creating and running servers and configuring maven (TOOLSDOC-357 - feel free to add any ideas for user testing). At that time I would probably move the runtime detection into the testing section.
* The 7.0 User Guide contains plenty of information about all of the necessary steps and different ways of creating servers when runtime detection has not been used.

I think your feedback for (3) really hinges on screenshots and that incorporating these will make the 7.0 guides clearer and provide users with examples. [Additionally, in time the User Guide will have an examples section for each plug-in, which again will add clarity - but that is obviously in the future and we need to resolve this now.] Time constraints mean 6.0 docs are not being updated unless there is a _major_ bug.

If you feel I have not addressed (3), please provide further information.

> Documentation on adding EAP to JBDS 7 is not as effective as documentation for JBDS 6
> -------------------------------------------------------------------------------------
>
>                 Key: TOOLSDOC-378
>                 URL: https://issues.jboss.org/browse/TOOLSDOC-378
>             Project: Documentation for JBoss Tools and Developer Studio
>          Issue Type: Bug
>      Security Level: Public(Everyone can see) 
>          Components: Getting Started Guide, Installation Guide
>    Affects Versions: 4.1.0
>            Reporter: Nick Boldt
>            Assignee: Michelle Murray
>
> For JBDS 6 we had this, complete with screenshots and example content:
> https://access.redhat.com/site/documentation/en-US/JBoss_Developer_Studio/6.0/html-single/Getting_Started_Guide/index.html#AddingJBossServer
> Now, we have this:
> {code:title=https://access.redhat.com/site/documentation/en-US/Red_Hat_JBoss_Developer_Studio/7.0/html-single/Getting_Started_Guide/index.html#Set_Up_a_Runtime_Server_Using_Server_Manager}
> 5.2. Set Up a Server Using Runtime Detection
>  Servers can be set up from within the Java EE Web Project wizard. But for the purposes of exploring JBoss Developer Studio the procedure below sets up the server first.
> Procedure 5.2. Set Up a Server Using Runtime Detection
>     Click Window→Preferences, expand JBoss Tools and select JBoss Tools Runtime Detection.
>     Click Add.
>     Select the directory containing the JBoss Enterprise Application Platform 6.0 or JBoss Enterprise Application Platform 6.1 installation and click OK. The directory is now scanned for application servers and JBoss Enterprise Application Platform 6.x found.
>     To create a server for JBoss Enterprise Application Platform 6.x, ensure the jboss-eap-6.x check box is selected and click OK.
>     Click Apply and click OK to close the Preferences window. The server is listed in the Servers tab.
>     The server is initially shown in stopped mode. To start the server, right-click jboss-eap-6.x and click Start. After a short pause, the view switches to the Console tab and shows the startup output of the server. 
> {code}
> AND we have this, which is more verbose but fails to mention any EAP 6.x specific examples.
> https://access.redhat.com/site/documentation/en-US/Red_Hat_JBoss_Developer_Studio/7.0/html/Installation_Guide/Set_up_Automatic_Runtime_Detection.html
> Additionally, the html anchor "Set_Up_a_Runtime_Server_Using_Server_Manager" for "5.2 Set Up a Server Using Runtime Detection" doesn't match the content. 
> https://access.redhat.com/site/documentation/en-US/Red_Hat_JBoss_Developer_Studio/7.0/html-single/Getting_Started_Guide/index.html#Set_Up_a_Runtime_Server_Using_Server_Manager
> -----
> Could the content in both places be updated/merged to equally complete, and could screenshots be added too?

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira