<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<body link="#355491" alink="#4262a1" vlink="#355491" style="background: #e2e2e2; margin: 0; padding: 20px;">

<div>
        <table cellpadding="0" bgcolor="#FFFFFF" border="0" cellspacing="0" style="border: 1px solid #dadada; margin-bottom: 30px; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
                <tbody>
                        <tr>

                                <td>

                                        <table border="0" cellpadding="0" cellspacing="0" bgcolor="#FFFFFF" style="border: solid 2px #ccc; background: #dadada; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
                                                <tbody>
                                                        <tr>
                                                                <td bgcolor="#000000" valign="middle" height="58px" style="border-bottom: 1px solid #ccc; padding: 20px; -moz-border-radius-topleft: 3px; -moz-border-radius-topright: 3px; -webkit-border-top-right-radius: 5px; -webkit-border-top-left-radius: 5px;">
                                                                        <h1 style="color: #333333; font: bold 22px Arial, Helvetica, sans-serif; margin: 0; display: block !important;">
                                                                        <!-- To have a header image/logo replace the name below with your img tag -->
                                                                        <!-- Email clients will render the images when the message is read so any image -->
                                                                        <!-- must be made available on a public server, so that all recipients can load the image. -->
                                                                        <a href="http://community.jboss.org/index.jspa" style="text-decoration: none; color: #E1E1E1">Community</a></h1>
                                                                </td>

                                                        </tr>
                                                        <tr>
                                                                <td bgcolor="#FFFFFF" style="font: normal 12px Arial, Helvetica, sans-serif; color:#333333; padding: 20px;  -moz-border-radius-bottomleft: 4px; -moz-border-radius-bottomright: 4px; -webkit-border-bottom-right-radius: 5px; -webkit-border-bottom-left-radius: 5px;"><h3 style="margin: 10px 0 5px; font-size: 17px; font-weight: normal;">
    How to Write Documentation for JBDS and JBoss Tools
</h3>
<span style="margin-bottom: 10px;">
    modified by <a href="http://community.jboss.org/people/smukhina">Svetlana Mukhina</a> in <i>JBoss Tools</i> - <a href="http://community.jboss.org/docs/DOC-14250">View the full document</a>
</span>
<hr style="margin: 20px 0; border: none; background-color: #dadada; height: 1px;">

<div class="jive-rendered-content"><p style="min-height: 8pt; height: 8pt; padding: 0px;"><span></span>&#160;</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h2><a class="jive-link-anchor-small" name="Places_of_main_Docteam_resources"><span style="font-size: 14pt;"><strong>Places of main doc team resources</strong></span></a></h2><p>Here is the list resources related to JBDS/Tools docs:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><ol start="1"><li>SVN - <a class="jive-link-external-small" href="https://svn.jboss.org/repos/jbosstools/trunk">https://svn.jboss.org/repos/jbosstools/trunk</a></li></ol><ul><li>doc folder with guide/guides is placed in plugin folder e.g. <a class="jive-link-external-small" href="https://svn.jboss.org/repos/jbosstools/trunk/esb/docs" target="_blank">https://svn.jboss.org/repos/jbosstools/trunk/esb/docs</a></li><li><a class="jive-link-external-small" href="https://svn.jboss.org/repos/jbosstools/documentation/trunk/movies">https://svn.jboss.org/repos/jbosstools/documentation/trunk/movies</a> - folder with movies on Tools and JBDS</li><li><a class="jive-link-external-small" href="https://svn.jboss.org/repos/jbosstools/trunk/documentation">https://svn.jboss.org/repos/jbosstools/trunk/documentation</a> - folder with doc resources and several guides.</li></ul><p class="MsoPlainText" style="padding-left: 30px;">&mdash; guides folder contains guides</p><p class="MsoPlainText" style="padding-left: 30px;">&mdash; jbds-docs folder is the place to generate JBDS release docs&#160; -jbosstool-docbook-xslt - xslt styles&#160; -jboss-tools-docs folder is the place to generate JBDS release docs&#160; -jboss-tools-docs-architype - architype for new guides creation&#160; -jbosstool-jdocbook-style -css styles</p><p class="MsoPlainText" style="padding-left: 30px;">&mdash; qa folder with qa resources (qa owns it)</p><p class="MsoPlainText" style="padding-left: 30px;">&mdash; whatsnew folder with what's new pages (dev team own it)</p><p class="MsoPlainText" style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText">&#160;&#160; 2. Doc project page contains links to release docs, nightly docs, movies &mdash; <a class="jive-link-external-small" href="http://jboss.org/tools/docs.html">http://jboss.org/tools/docs.html</a></p><ul><li>NEWS - owned by dev team</li><li>reference guides - release guides updated by us</li><li>screen casts - movies we have made</li><li>FAQ - owned by dev team</li></ul><p class="MsoPlainText" style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText">&#160;&#160; 3. Doc JIRA for both tools and jbds doc projects is on jbds project JIRA &mdash;&#160; <a class="jive-link-external-small" href="https://jira.jboss.org/jira/browse/JBDS">https://jira.jboss.org/jira/browse/JBDS</a></p><ul><li>open components tab - here is a list of components, doc component are ones with Doc- prefix.</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h2><a class="jive-link-anchor-small" name="Documentation_building_procedure"><span style="font-size: 14pt;"><strong>Documentation building procedure</strong></span></a></h2><p class="MsoPlainText">Here is an article on documentation building procedure <a class="jive-link-external-small" href="http://jboss.org/community/wiki/BuildingJBossToolsDocumentaion">http://jboss.org/community/wiki/BuildingJBossToolsDocumentaion</a></p><p class="MsoPlainText">Read it and try to build the docs with different profiles from here <a class="jive-link-external-small" href="https://svn.jboss.org/repos/jbosstools/trunk/documentation">https://svn.jboss.org/repos/jbosstools/trunk/documentation</a></p><h2><a class="jive-link-anchor-small" name="Doc_JIRA"><span style="font-size: 14pt;"><strong>Doc JIRA</strong></span></a></h2><p class="MsoPlainText">Here is JBDS JIRA - <a class="jive-link-external-small" href="https://jira.jboss.org/jira/browse/jbds">https://jira.jboss.org/jira/browse/jbds</a></p><p class="MsoPlainText" style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText">On the Open Issues&#160; tab you can see the components, the docs ones have Doc- prefix. Usually when a new guide is created I asked Max to add a component for it, as it's very convenient to use guides names as components. New doc JIRA issue usually is created basing on developers' taks, to find the tasks that affects docs use filter with "affects documentation" check-box marked.</p><p class="MsoPlainText" style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText">Most of the issues that affects docs can be found in JBoss Tools JIRA - <a class="jive-link-external-small" href="https://jira.jboss.org/jira/browse/JBIDE">https://jira.jboss.org/jira/browse/JBIDE</a>. When a doc task is created basing on a dev task, the tasks are linked to each other with "is related to" link.</p><p class="MsoPlainText" style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h2><a class="jive-link-anchor-small" name="JBDS_Demos"><span style="font-size: 14pt;"><strong>JBoss Tools/JBDS Demos</strong></span></a></h2><h3>Enviroment</h3><p>JBoss Tools/JBDS Demos should be created on Ubuntu with Red Hat Theme (Clearlook Controls and Windows Borders, Bluecurve Icons and Pointer). Ubuntu Fonts should be set with gray-scale smoothing and without Hinting.</p><p>You can capture demos on Ubuntu in Wink 1.5. The existing demos should be edited on Windows in Wink 2.0</p><h3>Wink Preferences</h3><p>You need to have the following resources in wink installation directory from <a class="jive-link-external-small" href="http://Wink%20Preferences%20You%20need%20to%20have%20the%20following%20resources%20in%20wink%20installation%20directory%20from%20http://anonsvn.jboss.org/repos/jbosstools/documentation/trunk/movies/common_resources/%20:%20%20JBoss%20flash%20preloaders%20and%20controlbars%20%28FlashPreloaders/%20%20and%20FlashControlBars/%20%29%20JBoss%20Buttons%20and%20Callouts%28Buttons/%20and%20Callouts/%29%20Color%20palette%20%28%20palette_for_demo_movies_%28256_colors%29.pal%20%29">http://anonsvn.jboss.org/repos/jbosstools/documentation/trunk/movies/common_resources/</a> :</p><ul><li>JBoss flash preloaders and controlbars (FlashPreloaders/&#160; and FlashControlBars/ )</li><li>JBoss Buttons and Callouts(Buttons/ and Callouts/)</li><li>Color palette ( palette_for_demo_movies_(256_colors).pal )</li></ul><h3>Screening process</h3><ul><li><p>Make window size is standard and small as possible (e.g. 1050*850 is suitable to 80% scaling)</p></li><li><p style="margin-bottom: 0cm;">Set time capture rate to be more or equal 4 (it's necessary for smooth pointer moving on the screen)</p></li><li><p>Capture all required actions</p></li><li><p style="margin-bottom: 0cm;">When making a demo, make sure that all application forms, hints, windows are not cut with demo frame<br/><a href="http://community.jboss.org/servlet/JiveServlet/showImage/102-14255-3-1596/image002.jpg"><span> http://community.jboss.org/servlet/JiveServlet/downloadImage/102-14255-3-1596/image002.jpg </span></a></p></li><li><p>Save it and load it in Wink 2.0 (it's more convenient to edit it in 2.0)</p></li><li>Resize all frames to 80%. Click in Main Menu <em><strong>Project &gt;&#160; Resize all frames</strong></em></li><li>Set frame duration as 0.2 sec in<em><strong> </strong><strong>Stay in this frame</strong></em> field of <strong>Property</strong> bar (top right side by default )</li><li><p style="font-style: normal;">Delete pauses, insert callouts with instruction and extra information. JBoss callouts and buttons names start with &ldquo;custom_&#8221;.</p></li><li><p style="margin-bottom: 0cm;">Make sure that you chose an appropriate size for hint boxes: unnecessary empty space should not be under the text and the box should look like all others, undamaged, because if you try to minimize it, it could change its form unproportionally, try to avoid such effect, minimize the box till its form (not size) remains the same.</p></li><li><p style="margin-bottom: 0cm;">When it&rsquo;s necessary to draw user attention to some particular element on a frame, use red ellipse (for small elements &ndash; tabs, buttons, etc.) or rectangle (for file lists, windows, etc.)</p></li><li><p style="margin-bottom: 0cm;"><span style="font-style: normal;"><span>Make sure all action&#160; you perform are observable for a user. Check that is </span></span>enough time to read text in hints, i<span style="font-style: normal;"><span>f it isn't, make frame duration longer.</span></span></p></li><li><p style="font-style: normal;">Set up preloaders and controlbars by selecting in Main Menu <em><strong>Project &gt; Setting </strong></em>and clicking<em><strong> Choose </strong></em>buttons.</p></li><li><p style="font-style: normal;">Enable Palette by selecting in Main Menu <em><strong>Project &gt; Setting </strong></em>and selecting<em><strong> Use Palette (reduce filesize) </strong></em>option</p></li><li><p style="font-style: normal;">Then render demo video</p></li><li><p style="font-style: normal;">Demo video is done!</p></li></ul><h2>Postprocessing</h2><p>When the video is designed, you need to publish it to the JBoss site.</p><p>For that you should insert&#160; resulted flash object in a demo html page. The Wink generates 3 files: examle.html, examle.swf and examle.js</p><p>For demo publishing take the code generated by Wink:</p><pre class="jive-pre"><code class="jive-code jive-xml">!-- examle.html --&gt;
<span class="jive-xml-comment">&lt;!-- saved from url=(0014)about:internet --&gt;</span>
<span class="jive-xml-tag">&lt;HTML&gt;</span>
<span class="jive-xml-tag">&lt;BODY&gt;</span>

<span class="jive-xml-tag">&lt;center&gt;</span><span class="jive-xml-tag"><span>&lt;OBJECT CLASSID="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" WIDTH="840" HEIGHT="700" CODEBASE="</span><a class="jive-link-external-small" href="http://active.macromedia.com/flash5/cabs/swflash.cab#version=7,0,0,0" target="_blank">http://active.macromedia.com/flash5/cabs/swflash.cab#version=7,0,0,0</a><span>"&gt;</span></span>
<span class="jive-xml-tag">&lt;PARAM NAME=movie VALUE="example.swf"&gt;</span>
<span class="jive-xml-tag">&lt;PARAM NAME=play VALUE=true&gt;</span>
<span class="jive-xml-tag">&lt;PARAM NAME=loop VALUE=false&gt;</span>
<span class="jive-xml-tag">&lt;PARAM NAME=wmode VALUE=transparent&gt;</span>
<span class="jive-xml-tag">&lt;PARAM NAME=quality VALUE=low&gt;</span>
<span class="jive-xml-tag"><span>&lt;EMBED SRC="example.swf" WIDTH=840 HEIGHT=700 quality=low loop=false wmode=transparent TYPE="application/x-shockwave-flash" PLUGINSPAGE="</span><a class="jive-link-external-small" href="http://www.macromedia.com/shockwave/download/index.cgi?P1_Prod_Version=ShockwaveFlash" target="_blank">http://www.macromedia.com/shockwave/download/index.cgi?P1_Prod_Version=ShockwaveFlash</a><span>"&gt;</span></span>
<span class="jive-xml-tag">&lt;/EMBED&gt;</span>
<span class="jive-xml-tag">&lt;/OBJECT&gt;</span><span class="jive-xml-tag">&lt;/center&gt;</span>

<span class="jive-xml-tag">&lt;SCRIPT src='example.js'&gt;</span><span class="jive-xml-tag">&lt;/script&gt;</span>

<span class="jive-xml-tag">&lt;/BODY&gt;</span>
<span class="jive-xml-tag">&lt;/HTML&gt;</span>

</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p style="margin-bottom: 0cm;">And paste OBJECT and SCRIPT from it to the following template:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><pre class="jive-pre"><code class="jive-code jive-xml"><span class="jive-xml-comment">&lt;!-- template.html --&gt;
<span class="jive-xml-tag">&lt;HTML&gt;</span>
<span class="jive-xml-tag">&lt;head&gt;</span>
<span class="jive-xml-tag">&lt;title&gt;</span>Importing Custom Tag Library to JBoss Tools Palette<span class="jive-xml-tag">&lt;/title&gt;</span>
<span class="jive-xml-tag">&lt;link rel="stylesheet" href="../../resources/tools.css" type="text/css"/&gt;</span>
<span class="jive-xml-tag">&lt;link xmlns="" rel="shortcut icon" type="image/vnd.microsoft.icon" href="../../resources/images/favicon.ico"/&gt;</span>
<span class="jive-xml-tag">&lt;/head&gt;</span>

<span class="jive-xml-tag">&lt;BODY&gt;</span>
<span class="jive-xml-tag">&lt;div class="book"&gt;</span>
<span class="jive-xml-tag">&lt;p id="title"&gt;</span><span class="jive-xml-tag"><span>&lt;a href="</span><a class="jive-link-external-small" href="http://www.jboss.org" target="_blank">http://www.jboss.org</a><span>" class="site_href"&gt;</span></span>
<span class="jive-xml-tag">&lt;strong&gt;</span>JBoss.org<span class="jive-xml-tag">&lt;/strong&gt;</span><span class="jive-xml-tag">&lt;/a&gt;</span><span class="jive-xml-tag"><span>&lt;a href="</span><a class="jive-link-external-small" href="http://docs.jboss.org/" target="_blank">http://docs.jboss.org/</a><span>" class="doc_href"&gt;</span></span>
<span class="jive-xml-tag">&lt;strong&#160;&#160;&#160; &gt;</span>Community Demos<span class="jive-xml-tag">&lt;/strong&gt;</span><span class="jive-xml-tag">&lt;/a&gt;</span><span class="jive-xml-tag">&lt;/p&gt;</span>

<span class="jive-xml-tag">&lt;center&gt;</span>

&lt;!--Place for <span class="jive-xml-tag">&lt;OBJECT/&gt;</span> --&gt;

<span class="jive-xml-tag">&lt;/center&gt;</span>
<span class="jive-xml-tag">&lt;/div&gt;</span>

&lt;!--Place for <span class="jive-xml-tag">&lt;SCRIPT/&gt;</span> --&gt;</span>

<span class="jive-xml-tag">&lt;/BODY&gt;</span>
<span class="jive-xml-tag">&lt;/HTML&gt;</span>
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p style="margin-bottom: 0cm;">Then put the resulted html page with example.js and example.swf on the server. At the end you need to add the source wink file to svn. For this save your demo in Wink as compressed by clicking <em><strong>Main Menu &gt; File &gt; Save Compressed</strong></em>.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h2><a class="jive-link-anchor-small" name="JBDS_guides_structure"><span style="font-size: 14pt;"><strong>JBoss Tools/JBDS guides structure</strong></span></a></h2><p>While creating a new or updating already existed JBoss Tools/JBDS guide, please keep to the following structure (JBoss Portlet Tools User Guide structure as an example):</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>1. Introduction<br/>&#160;&#160;&#160; 1.1. What is JBoss Portal and Portlet Tools?<br/>&#160;&#160;&#160; 1.2. Key Features of JBoss Portlet Tools<br/>&#160;&#160;&#160; 1.3. Requirements and Installation<br/>2. JBoss Portlet Tools Tasks<br/>&#160;&#160;&#160; 2.1. Creating and Deploying a Java Portlet<br/>&#160;&#160;&#160;&#160;&#160;&#160;&#160; 2.1.1. Creating a Web Project with JBoss Portlet Capabilities<br/>&#160;&#160;&#160;&#160;&#160;&#160;&#160; 2.1.2. Adding a Java Portlet to a Web Project<br/>&#160;&#160;&#160;&#160;&#160;&#160;&#160; 2.1.3. Deploying a Portlet to JBoss Portal<br/>&#160;&#160;&#160; 2.2. Creating and Deploying a JSF Portlet<br/>&#160;&#160;&#160;&#160;&#160;&#160;&#160; 2.2.1. Creating a JSF Project with JSF Portlet Capabilities<br/>&#160;&#160;&#160;&#160;&#160;&#160;&#160; 2.2.2. Adding a JSF Protlet to the Project and Deploying It to JBoss Portal<br/>&#160;&#160;&#160; 2.3. Creating and Deploying a Seam Portlet<br/>&#160;&#160;&#160;&#160;&#160;&#160;&#160; 2.3.1. Creating a Seam Project with Seam Portlet Capabilities<br/>&#160;&#160;&#160;&#160;&#160;&#160;&#160; 2.3.2. Adding a Seam Protlet to the Project and Deploying It to JBoss Portal</p><p>3. Reference<br/>&#160;&#160;&#160;&#160;&#160;&#160;&#160; 3.1. JBoss Portlet Descriptors<br/>&#160;&#160;&#160;&#160;&#160;&#160;&#160; 3.2. Wizards<br/>&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; 3.2.1. Java Portlet Wizard<br/>&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; 3.2.2. JSF/Seam Portlet Wizard<br/>&#160;&#160;&#160;&#160;&#160;&#160;&#160; 3.3. JBoss Portlet Preferences<br/>4. Summary<br/>&#160;&#160;&#160; 4.1. Other Relevant Resources on the Topic</p><p><strong><br/></strong></p><p><strong>Comments:</strong></p><ul><li>The "Key Features of [plugin name]" section should contain the table included key features (wizards, editors, tasks, etc.) of the plugin you're describing with short descriptions and references to the appropriate guide section.</li><li>The "Requirements and Installation" section should provide minimal requirements on the environment the plugin needs and installation procedure (or reference to it).</li><li>All procedural operations must be put into the "[plugin name] Tasks" chapter.&#160; Each section of the chapter is a tutorial on a particular topic.</li><li>The referential data should be stored in the "Reference" chapter.</li><li>Remember to summarize the results and provide the links to other relevent resources in the "Summary" chapter.</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h2><a class="jive-link-anchor-small" name="Project_structure_schema"><span style="font-size: 14pt;"><strong>Project structure schema</strong></span></a></h2><p class="MsoPlainText"><span style="font-family: Arial,sans-serif; font-size: 10pt;">In case you need to show some project structure in the documentation you should use the "tree" utility that builds in terminal the project structure that you can copy/paste to your docs. Quite likely that the "tree" utility is not installed on your local machine, the <span style="font-family: &amp;quot;Courier New&amp;quot;, Courier;">sudo apt-get install tree</span> command will install this utility. You need to create the project structure schema in Linux since the <span style="font-family: &amp;quot;Courier New&amp;quot;, Courier;">tree</span> command in Windows draws a tree that is not as nice as the one in Linux, besides Linux is our primary OS.</span> However if you still need to draw a tree in Windows please use the <span style="font-family: &amp;quot;Courier New&amp;quot;, Courier;">tree /a /f</span> command. <span style="font-family: Arial,sans-serif; font-size: 10pt;">This is what the project structure should be like.</span></p><p class="MsoPlainText" style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText">|-- pom.xml</p><p class="MsoPlainText">`-- src</p><p class="MsoPlainText">&#160;&#160;&#160; |-- main</p><p class="MsoPlainText">&#160;&#160;&#160; |&#160;&#160; |-- java</p><p class="MsoPlainText">&#160;&#160;&#160; |&#160;&#160; |&#160;&#160; `-- org</p><p class="MsoPlainText">&#160;&#160;&#160; |&#160;&#160; |&#160;&#160;&#160;&#160;&#160;&#160; `-- docs</p><p class="MsoPlainText">&#160;&#160;&#160; |&#160;&#160; |&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; `-- richfaces</p><p class="MsoPlainText">&#160;&#160;&#160; |&#160;&#160; |&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; `-- Bean.java</p><p class="MsoPlainText">&#160;&#160;&#160; |&#160;&#160; |-- resources</p><p class="MsoPlainText">&#160;&#160;&#160; |&#160;&#160; `-- webapp</p><p class="MsoPlainText">&#160;&#160;&#160; |&#160;&#160;&#160;&#160;&#160;&#160; |-- WEB-INF</p><p class="MsoPlainText">&#160;&#160;&#160; |&#160;&#160;&#160;&#160;&#160;&#160; |&#160;&#160; |-- faces-config.xml</p><p class="MsoPlainText">&#160;&#160;&#160; |&#160;&#160;&#160;&#160;&#160;&#160; |&#160;&#160; `-- web.xml</p><p class="MsoPlainText">&#160;&#160;&#160; |&#160;&#160;&#160;&#160;&#160;&#160; |-- index.jsp</p><p class="MsoPlainText">&#160;&#160;&#160; |&#160;&#160;&#160;&#160;&#160;&#160; `-- pages</p><p class="MsoPlainText">&#160;&#160;&#160; |&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; |-- index.jsp</p><p class="MsoPlainText">&#160;&#160;&#160; |&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; `-- index.xhtml</p><p class="MsoPlainText">&#160;&#160;&#160; `-- test</p><p class="MsoPlainText">&#160;&#160;&#160;&#160;&#160;&#160;&#160; `-- java</p><p class="MsoPlainText">&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; `-- org</p><p class="MsoPlainText">&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; `-- docs</p><p class="MsoPlainText">&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; `-- richfaces</p><p class="MsoPlainText">&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; `-- BeanTest.java</p><p class="MsoPlainText" style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h2><a class="jive-link-anchor-small" name="Inline_graphics_scale"><span style="font-size: 14pt;"><strong>Inline graphics scale - 100%</strong></span></a></h2><p class="MsoPlainText">When inserting an inline graphics element please leave it unscaled. If&#160; you&#160;&#160; scale a tiny inline element, the image will be broken and hardly&#160; readable.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h2><a class="jive-link-anchor-small" name="Doc_build_process_speed_up"><span style="font-size: 14pt;"><strong>Doc build process speed up</strong></span></a></h2><p class="MsoPlainText">Command line option for only creating part of the outputs to speed up roundtrip.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p>See the issue for details <a class="jive-link-external-small" href="https://jira.jboss.org/jira/browse/MPJDOCBOOK-7" target="_blank">https://jira.jboss.org/jira/browse/MPJDOCBOOK-7</a></p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h2><a class="jive-link-anchor-small" name="Task_reviewing"><span style="font-size: 14pt;"><strong>Task reviewing</strong></span></a></h2><p class="MsoPlainText">When writing some article or component description or complicated section/chapter and need some review of it, let me know plz, and I&rsquo;ll try to find a reviewer for your task.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h2><a class="jive-link-anchor-small" name="Text_validation"><span style="font-size: 14pt;"><strong>Text validation</strong></span></a></h2><p class="MsoPlainText">E.g.&#160; letter &ldquo;p&#8221; inside two opening tags (&lt;section&gt;p &lt;title&gt;&#8230; ) makes&#160; the document invalid and failes <span style="font-size: 10pt;">the build on this place. Do not forget to validate xmls each time you make changes.</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h2><a class="jive-link-anchor-small" name="JBDS_team_movies_update"><span style="font-size: 14pt;"><strong><strong>JBDS team movies update</strong></strong></span></a></h2><p class="MsoPlainText">When updating the guides according to some dev issue, remember about our movies collection, it also should be updated.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h2><a class="jive-link-anchor-small" name="Inline_graphics"><span style="font-size: 14pt;"><strong>JBDS Inline graphics</strong></span></a></h2><p>Documenting&#160; UI, from time to time you talk about icons, mouse arrows that change depending on the user behavior etc. In these cases you can insert an image of the element into the documentation right into the text. DocBook allows you to embed inline graphics using:</p><p class="MsoNormal" style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p><span style="color: black; font-size: 12pt;">&#160;&#160;&#160;&#160;&#160; </span> <span style="color: #000096; font-size: 12pt;">&lt;inlinemediaobject&gt;</span><span style="color: black; font-size: 12pt;"> </span></p><p><span style="color: black; font-size: 12pt;">&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; </span> <span style="color: #000096; font-size: 12pt;">&lt;imageobject&gt;</span><span style="color: black; font-size: 12pt;"><br/>&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; </span> <span style="color: #000096; font-size: 12pt;">&lt;imagedata</span> <span style="color: #f5844c; font-size: 12pt;">fileref</span><span style="color: #ff8040; font-size: 12pt;">=</span><span style="color: #993300; font-size: 12pt;">"images/image1.png"</span><span style="color: #000096; font-size: 12pt;">/&gt;</span><span style="color: black; font-size: 12pt;"><br/>&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; </span> <span style="color: #000096; font-size: 12pt;">&lt;/imageobject&gt;</span><span style="color: black; font-size: 12pt;"><br/>&#160;&#160;&#160;&#160;&#160;&#160;&#160; </span> <span style="color: #000096; font-size: 12pt;">&lt;/inlinemediaobject&gt;</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h2><a class="jive-link-anchor-small" name="Task_resolving_before_release"><span style="font-size: 14pt;"><strong>Task resolving before a release</strong></span></a></h2><p><a class="jive-link-external-small" href="https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-docs/pom.xml">https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-docs/pom.xml</a></p><p class="MsoPlainText">When you&rsquo;re resolving a task, make sure that the person who will be closing the task, has enough time for its verification.</p><p class="MsoPlainText">E.g. if you resolve the task in a release day it means that QA or a person who needs to verify the task, has no time for it, and also you won&rsquo;t have time to fix the task if it&rsquo;s reopened.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h2><a class="jive-link-anchor-small" name="JIRA_issues"><span style="font-size: 14pt;"><strong>JIRA issues</strong></span></a></h2><p class="MsoPlainText"><strong>JIRA issues format.</strong></p><p class="MsoPlainText">All your tasks in JIRA should have versions and components defined.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText"><strong>JIRA issues resolution.</strong></p><p class="MsoPlainText">When closing an issue, plz write some resolution as the last comment about what exactly was done.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText"><strong>"Fix version" of a jira issue.</strong></p><p class="MsoPlainText">When closing or resolving a jira issue, make sure &ldquo;fix version&#8221; is the correct one, it must correspond to the next release version, which could be found on project jira page on Version tab.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h2><a class="jive-link-anchor-small" name="Para_and_programlisting"><span style="font-size: 14pt;"><strong>Para and programlisting</strong></span></a></h2><p class="MsoPlainText">Don&rsquo;t insert programlisting into para tags, it causes damaged code on a page.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h2><a class="jive-link-anchor-small" name="Image_canvas_size"><span style="font-size: 14pt;"><strong>Image canvas size</strong></span></a></h2><p class="MsoPlainText">When print-screening an image, please make sure that canvas size (uninformative white space around) of it is not to large, if yes, trim it.</p><h2><strong><a class="jive-link-anchor-small" name="Image_canvas_size"><span style="font-size: 14pt;">Docs</span> <span style="font-size: 14pt;">releasing procedure</span></a></strong></h2><p class="MsoPlainText">The first step you have to do is to generate new master_output.xml files for all the guides that will be included into the bundle.</p><h3><a class="jive-link-anchor-small" name="Using_Diffmk"><span style="font-size: 14pt;"><strong style="font-size: 12pt; ">Using diffmk to add updated/added markers to TOC</strong></span></a></h3><p class="MsoPlainText"><span style="font-family: arial,helvetica,sans-serif; font-size: 10pt;">This procedure is required because it is necessary to compare documentation of the previous release version with the current one and add update/added markers to TOC, we use DiffMk version 3.0.a1. tool.</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText"><span style="font-family: arial,helvetica,sans-serif; font-size: 10pt;">We added two script files in the</span> <span style="font-family: courier new,courier; font-size: 10pt;">bin</span> <span style="font-family: arial,helvetica,sans-serif; font-size: 10pt;">folder of the DiffMk distribution:</span></p><ul><li>run.sh</li><li>run_mkdiff.sh.</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText"><span style="font-family: arial,helvetica,sans-serif; font-size: 10pt;">The first is responsible for comparing 2 files and producing a third file with *diff* markers. The second one we use to indicate the files to compare and the output files, the format is the following: ./run.sh [<em>the path to the file</em>] [<em>the path to the file modified</em>] [<em>the path to the output file</em>]</span></p><p class="MsoPlainText" style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText"><span style="font-family: arial,helvetica,sans-serif; font-size: 10pt;">To identify the changes between two different revisions of the same guide, use the following line:</span> <span style="font-family: courier new,courier;">./run.sh /path/to/the/old/revision/guide/master.xml /path/to/the/current/revision/guide/master.xml /path/to/the/produced/by/diffmk/master_output.xml</span></p><p class="MsoPlainText" style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText"><span style="font-family: arial,helvetica,sans-serif; font-size: 10pt;">Next, run the</span> <span style="font-family: courier new,courier;">run_mkdiff.sh</span></p><p class="MsoPlainText" style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText"><span style="font-family: arial,helvetica,sans-serif; font-size: 10pt;">Actually, the DiffMk is not an ideal tool for comparing. It has a lot of lacks. Here are some of such lacks we run into:</span></p><ul><li>It removes the HTML entities when outputs the file, for instance &amp;amp; in the links;</li><li>Sometimes it mixes the structure of the document, for instance, put the &lt;chapter&gt; into the &lt;chapter&gt;;</li><li>Sometimes it deletes the tags such as &lt;imageobject&gt;.</li></ul><p class="MsoPlainText" style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText"><span style="font-family: arial,helvetica,sans-serif; font-size: 10pt;">Thus, in order to build the docs with diff markers, the next step is validating and checking the <span style="font-family: courier new,courier;">master_output.xml</span> files carefully.</span></p><p class="MsoPlainText" style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText"><span style="font-family: arial,helvetica,sans-serif; font-size: 10pt;">When the check and </span><span style="font-family: arial,helvetica,sans-serif; font-size: 10pt;">validation</span><span style="font-family: arial,helvetica,sans-serif; font-size: 10pt;"> is done the next step you have to do is to build documentation bundle with updated/new markers on the TOC and required styles.</span></p><h2></h2><h3><a class="jive-link-anchor-small" name="Using_Diffmk"><span style="font-size: 14pt;"><strong style="font-size: 12pt; ">Documentation build procedure</strong></span></a></h3><p class="MsoPlainText"><span style="font-family: arial,helvetica,sans-serif; font-size: 10pt;">Here we have to admit that doc bundels for JBDS and JBT releases differ from each other.JBDS documentation has "com"(red styles), while JBT docs are built in blue ones("org" styles).If you need&#160; JBDS doc release bundle,please, use "releaseJBDS" profile,othervise <span lang="EN"> </span></span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"><span style="font-family: arial,helvetica,sans-serif; font-size: 10pt;"><span lang="EN"> </span></span>&#160;</p><p>"release" profile meets your needs.</p><p>You can build release guides one by one using</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText"><span style="font-size: 10pt; font-family: courier new,courier; ">mvn clean install -P releaseJBDS</span></p><p class="MsoPlainText"><span style="font-family: arial,helvetica,sans-serif; font-size: 10pt;">or</span></p><p class="MsoPlainText"><span style="font-size: 10pt; font-family: courier new,courier; ">mvn clean install -P release</span></p><p class="MsoPlainText"><span style="font-family: arial,helvetica,sans-serif; font-size: 10pt;">maven command and then collect all the docs together.</span></p><p class="MsoPlainText" style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText"><span style="font-family: arial,helvetica,sans-serif; font-size: 10pt;">But the least time-consuming method is to build the whole bundle from <em>jbosstools_trunk\documentation\jboss-tools-docs</em>&#160; directory using</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p><span style="font-size: 10pt; font-family: courier new,courier; ">mvn assembly:assembly -P releaseJBDS</span></p><p><span style="font-family: arial,helvetica,sans-serif; font-size: 10pt;">or</span></p><p><span style="font-size: 10pt; font-family: courier new,courier; ">mvn assembly:assembly -P release</span></p><p><span style="font-size: 10pt; font-family: courier new,courier; "> <span style="font-family: arial,helvetica,sans-serif;">maven command.After it </span></span><span style="font-size: 10pt; font-family: arial,helvetica,sans-serif; ">all the guides </span><span style="font-size: 10pt; font-family: courier new,courier; "><span style="font-family: arial,helvetica,sans-serif;">will be built and collected in </span><em>nightly-docs/en</em> <span style="font-family: arial,helvetica,sans-serif;">folder.</span></span></p><p><span style="font-size: 10pt; font-family: courier new,courier; "><br/></span></p><p style="padding-left: 30px;"><span style="font-size: 10pt; font-family: courier new,courier; "><em>Note,that <strong>eclipse</strong> guides' versions should be excluded from the final version of the bundle.</em></span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><h3><a class="jive-link-anchor-small" name="Using_Diffmk"><span style="font-size: 14pt;"><strong style="font-size: 12pt; ">Upload to the site</strong></span></a></h3><p><span style="font-size: 12pt; font-family: times new roman,times; ">I<span style="font-size: 10pt; font-family: arial,helvetica,sans-serif; ">n the end the created release bundle should be uploaded to the site.</span></span></p><p><span style="font-size: 10pt; font-family: courier new,courier; "><span style="font-size: 10pt; font-family: arial,helvetica,sans-serif; ">JBDS release documentation should be placed here:</span><a class="jive-link-external-small" href="http://www.redhat.com/docs/en-US/JBoss_Developer_Studio/">http://www.redhat.com/docs/en-US/JBoss_Developer_Studio/</a></span></p><p><span style=": ; font-size: 10pt; font-family: courier new,courier; "><span style="font-family: arial,helvetica,sans-serif;">while JBT release documentation should be here:</span> <a class="jive-link-external-small" href="http://docs.jboss.org/tools/">http://docs.jboss.org/tools/</a>.</span></p><p><span style=": ; font-size: 10pt; font-family: courier new,courier; "><br/></span></p><h2><a class="jive-link-anchor-small" name="Nightly_docs"><span style="font-size: 14pt;"><strong>Nightly docs</strong></span></a></h2><p class="MsoPlainText">Nightly docs online:</p><p class="MsoPlainText"><a class="jive-link-external-small" href="http://download.jboss.org/jbosstools/nightly-docs/">http://download.jboss.org/jbosstools/nightly-docs/</a></p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText">Here is svn for it:</p><p class="MsoPlainText"><a class="jive-link-external-small" href="https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-docs">https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-docs</a></p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText">Here is Hudson for it:</p><p class="MsoPlainText"><a class="jive-link-external-small" href="http://hudson.qa.jboss.com/hudson/job/jbosstools-docs-nightly/">http://hudson.qa.jboss.com/hudson/job/jbosstools-docs-nightly/</a> (to build nightly docs VPN access and admin pass are required)</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText">When a new guide is created it should be added to nightly docs build</p><ul><li>add it to pom.xml: <a class="jive-link-external-small" href="https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-docs/pom.xml">https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-docs/pom.xml</a></li></ul><p><a class="jive-link-external-small" href="https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-docs/pom.xml">https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-docs/pom.xml</a></p><ul><li><span style="font-size: 11pt; font-family: &amp;quot;Calibri&amp;quot;,&amp;quot;sans-serif&amp;quot;;">add it to all-guides.xml:</span> <a class="jive-link-external-small" href="https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-docs/all-guides.xml">https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-docs/all-guides.xml</a></li><li>add it to the index.html (master.xml) page: <a class="jive-link-external-small" href="https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-docs/index/en/master.xml">https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-docs/index/en/master.xml</a></li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText">See that the guide is added and email Denis Golovin asking to add a new guide to the server settings for nightly docs.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><p class="MsoPlainText">Build the guides with <span style="font-family: courier new,courier;">mvn clean install</span> from <a class="jive-link-external-small" href="https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-docs">https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-docs</a></p><div id="_mcePaste" style="overflow: hidden; position: absolute; width: 1px; height: 1px; top: 0px; left: -10000px;"><p style="min-height: 8pt; height: 8pt; padding: 0px;">&#160;</p><a class="jive-link-wiki-small" href="http://community.jboss.org/docs/DOC-14252">Places of main Docteam resources</a></div></div>

<div style="background-color: #f4f4f4; padding: 10px; margin-top: 20px;">
    <p style="margin: 0;">Comment by <a href="http://community.jboss.org/docs/DOC-14250">going to Community</a></p>

        <p style="margin: 0;">Create a new document in JBoss Tools at <a href="http://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2128">Community</a></p>
</div></td>
                        </tr>
                    </tbody>
                </table>


                </td>
            </tr>
        </tbody>
    </table>

</div>

</body>
</html>