Bug 1121461 - Not clear that XML snippets are auto-generated
Summary: Not clear that XML snippets are auto-generated
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: JBoss Fuse Service Works 6
Classification: JBoss
Component: Documentation
Version: 6.0.0
Hardware: Unspecified
OS: Unspecified
urgent
unspecified
Target Milestone: CR3
: 6.0.0
Assignee: belong
QA Contact: Len DiMaggio
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2014-07-21 03:59 UTC by belong
Modified: 2014-07-31 04:04 UTC (History)
2 users (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of:
Environment:
Last Closed: 2014-07-31 04:04:49 UTC
Type: Bug


Attachments (Terms of Use)

Description belong 2014-07-21 03:59:45 UTC
It has been reported by SAs that it is not clear from our docs that the XML provided in the SwitchYard Dev guide is auto-generated.

Comment 1 belong 2014-07-21 04:30:00 UTC
I have so far added example tags with title 'Generated XML Sample' to each topic in 'Application Basics'.

Comment 2 belong 2014-07-22 02:31:56 UTC
SMEs say that although users cannot modify the XML directly from within JBDS, we should not forbid them from doing so at all (outside of the tooling).

Modified introductory chapter [1] accordingly:

1. Added example tags with title 'Sample Corresponding XML'.
2. Reworded overview topic [1]. "Each topic includes a visual representation of the switchyard.xml configuration file as designed in the SwitchYard graphical editor and the corresponding source XML which is automatically generated from the visual design. NOTE: Users cannot modify the switchyard.xml file directly from the Source tab. There is generally no need to view or edit the XML; however, we provide the XML in our documentation to assist our more advanced users."

[1] http://docbuilder.usersys.redhat.com/16862/#chap-Application_Basics

Comment 3 belong 2014-07-22 02:38:44 UTC
Len,

It has been reported by SAs that it is not clear from our docs that the XML provided in the SwitchYard Dev guide is auto-generated.

Please verify for patch to 6.0 docs:

1. All XML snippets in 'Application Basics' chapter now introduced as 'Sample Corresponding XML'.
2. Reworded 'Application Basics' overview topic as described in Comment 2.

Regards,
Ben

Comment 4 belong 2014-07-23 05:40:16 UTC
I am making more changes for this and seeking more feedback from SAs/GSS etc.

See http://docbuilder.usersys.redhat.com/16894/#Editing_the_SwitchYard_Configuration_File

Comment 5 belong 2014-07-24 01:00:14 UTC
Summary of changes to 6.0 SwitchYard Dev Guide:

1. Added chapter on JBoss Integration and SOA Development [1], including a lot of new information on editing the SY config file [2].
2. Reworded Application Basics [3] chapter overview: "Each topic includes a visual representation of the switchyard.xml configuration file as designed in the SwitchYard graphical editor and the corresponding source XML which is automatically generated from the visual design. "
3. Added 'example' tags to all topics in Application Basics [3] stating 'Sample Corresponding XML'.


[1] http://docbuilder.usersys.redhat.com/22584/#chap-JBoss_Integration_and_SOA_Development
[2] http://docbuilder.usersys.redhat.com/22584/#Editing_the_SwitchYard_Configuration_File
[3] http://docbuilder.usersys.redhat.com/22584/#chap-Application_Basics

Comment 6 belong 2014-07-24 01:01:30 UTC
Len,

Please review and verify changes (see Comment 5) to the 6.0 SwitchYard dev guide.

Note: These changes will also feed into the 6.1 docs.

Regards,
Ben

Comment 7 Len DiMaggio 2014-07-24 02:10:04 UTC
I don't think that it is a good idea to have users hand editing the XML source. It is very easy to introduce an error that will be difficult to debug. 

Can we add a warning/suggestion that users attempt to always use the editor?

I was also wondering - can an SME or SA provide an example of a situation when a user would be compelled to hand edit the XML?

Comment 8 belong 2014-07-24 02:24:01 UTC
Added warning.

Please verify [1].

[1] http://docbuilder.usersys.redhat.com/22584/#Editing_the_SwitchYard_Configuration_File

Comment 9 Len DiMaggio 2014-07-24 02:26:53 UTC
Verified!

Comment 10 belong 2014-07-31 04:04:49 UTC
Published live!

Build: Red_Hat_JBoss_Fuse_Service_Works-Development_Guide_Volume_1_SwitchYard-6-web-en-US-6.0.0-20


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