<!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">JBoss 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;">
Documentation notes
</h3>
<span style="margin-bottom: 10px;">
modified by <a href="http://community.jboss.org/people/admin">Administrator Administrator</a> in <i>JBoss Tools</i> - <a href="http://community.jboss.org/docs/DOC-14255">View the full document</a>
</span>
<hr style="margin: 20px 0; border: none; background-color: #dadada; height: 1px;">
<div class="jive-rendered-content"><span>← back to </span><a class="jive-link-wiki-small active_link" href="../../docs/DOC-14250">How to write documentation for JBDS and JBoss Tools </a><p class="MsoPlainText" style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p class="MsoPlainText" style="min-height: 8pt; height: 8pt; padding: 0px;"><span style="font-family: arial,helvetica,sans-serif; font-size: 10pt;"> </span> </p><p class="MsoPlainText"><span style="font-family: arial,helvetica,sans-serif; font-size: 10pt;"><strong>1. Project structure schema.</strong></span></p><p class="MsoPlainText"><span style="font-family: arial,helvetica,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: courier new,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: courier new,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: courier new,courier;">tree /a /f</span> command. <span style="font-family: arial,helvetica,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;"> </p><p class="MsoPlainText">|-- pom.xml</p><p class="MsoPlainText">`-- src</p><p class="MsoPlainText"><span>    </span>|-- main</p><p class="MsoPlainText"><span>    </span>|<span>   </span>|-- java</p><p class="MsoPlainText"><span>    </span>|<span>   </span>|<span>   </span>`-- org</p><p class="MsoPlainText"><span>    </span>|<span>   </span>|<span>       </span>`-- docs</p><p class="MsoPlainText"><span>    </span>|<span>   </span>|<span>           </span>`-- richfaces</p><p class="MsoPlainText"><span>    </span>|<span>   </span>|<span>               </span>`-- Bean.java</p><p class="MsoPlainText"><span>    </span>|<span>   </span>|-- resources</p><p class="MsoPlainText"><span>    </span>|<span>   </span>`-- webapp</p><p class="MsoPlainText"><span>    </span>|<span>       </span>|-- WEB-INF</p><p class="MsoPlainText"><span>    </span>|<span>       </span>|<span>   </span>|-- faces-config.xml</p><p class="MsoPlainText"><span>    </span>|<span>       </span>|<span>   </span>`-- web.xml</p><p class="MsoPlainText"><span>    </span>|<span>       </span>|-- index.jsp</p><p class="MsoPlainText"><span>    </span>|<span>       </span>`-- pages</p><p class="MsoPlainText"><span>    </span>|<span>           </span>|-- index.jsp</p><p class="MsoPlainText"><span>    </span>|<span>           </span>`-- index.xhtml</p><p class="MsoPlainText"><span>    </span>`-- test</p><p class="MsoPlainText"><span>        </span>`-- java</p><p class="MsoPlainText"><span>            </span>`-- org</p><p class="MsoPlainText"><span>                </span>`-- docs</p><p class="MsoPlainText"><span>      </span><span>              </span>`-- richfaces</p><p class="MsoPlainText"><span>                        </span>`-- BeanTest.java</p><p class="MsoPlainText" style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p class="MsoPlainText"><strong style="font-family: arial,helvetica,sans-serif; font-size: 10pt;">2. Inline graphics scale - 100%.</strong></p><p class="MsoPlainText"><span style="font-size: 10pt;">When inserting an inline graphics element please leave it unscaled. If  you   scale a tiny inline element, the image will be broken and hardly  readable. </span></p><p class="MsoPlainText" style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p class="MsoPlainText"><strong style="font-family: arial,helvetica,sans-serif; font-size: 10pt;">3. Doc build process speed up.</strong></p><p class="MsoNormal"><span style="font-size: 10pt;">Command line option for only creating part of the outputs to speed up roundtrip</span></p><p class="MsoNormal"><span style="font-size: 10pt;">See the issue for details <a class="jive-link-external-small" href="https://jira.jboss.org/jira/browse/MPJDOCBOOK-7">https://jira.jboss.org/jira/browse/MPJDOCBOOK-7</a></span></p><p class="MsoNormal" style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p class="MsoNormal"><strong>4. Task reviewing.</strong></p><p class="MsoNormal"><span style="font-size: 10pt;">When writing some article or component description or complicated section/chapter and need some review of it, let me know plz, and I’ll try to find a reviewer for you task. </span></p><p class="MsoNormal" style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p class="MsoNormal"><strong>5. Text validation.</strong></p><p class="MsoNormal"><span style="font-size: 10pt;">E.g.  letter “p” inside two opening tags (<section>p <title>… ) makes  the document invalid and failes </span><span style="font-size: 10pt;">the build</span><span style="font-size: 10pt;"> on this place. </span><span style="font-size: 10pt;">Do not forget to validate xmls e</span><span style="font-size: 10pt;">ach time you make changes.</span></p><p class="MsoNormal" style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p class="MsoNormal"><strong>6. JBDS team. movies update.</strong></p><p class="MsoNormal"><span style="font-size: 10pt;">When updating the guides according to some dev issue, remember about our movies collection, it also should be updated. </span></p><p class="MsoNormal" style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p class="MsoNormal"><strong>7. Inline graphics.</strong></p><p>Documenting  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;"><span style="font-size: 11pt; color: #1f497d;"> </span> </p><p><span style="color: black; font-size: 12pt;">        </span><span style="color: #000096; font-size: 12pt;"><inlinemediaobject></span><span style="color: black; font-size: 12pt;">   </span></p><p><span style="color: black; font-size: 12pt;">             </span><span style="color: #000096; font-size: 12pt;"><imageobject></span><span style="color: black; font-size: 12pt;"><br/>                 </span><span style="color: #000096; font-size: 12pt;"><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;">/></span><span style="color: black; font-size: 12pt;"><br/>             </span><span style="color: #000096; font-size: 12pt;"></imageobject></span><span style="color: black; font-size: 12pt;"><br/>          </span><span style="color: #000096; font-size: 12pt;"></inlinemediaobject></span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><strong> 8. Task resolving before a release.</strong> <span> </span><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="MsoNormal"><span style="font-size: 10pt;">When you’re resolving a task, make sure that the person who will be closing the task, has enough time for its verification. </span></p><p class="MsoNormal"><span style="font-size: 10pt;">E.g. if you resolve the task in </span><span style="font-size: 10pt;">a release </span><span style="font-size: 10pt;">day it means that QA or a person who needs to verify the task, has no time for it, and also you won’t have time to fix the task if it’s reopened. </span></p><br/><strong>9. "Fix version" of a jira issue.</strong><br/><p class="MsoNormal"><span style="font-size: 10pt;">When closing or resolving a jira issue, make sure “fix version” is the correct one, it must correspond to the next release version, which could be found on project jira page on Version tab.</span></p><p class="MsoNormal" style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p class="MsoNormal"><strong>10. JIRA issues resolution.</strong></p><p class="MsoNormal"><span style="font-size: 10pt;">When closing an issue, plz write some resolution as the last comment about what exactly was done.</span></p><p class="MsoNormal" style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p class="MsoNormal"><strong>11. Para and programlisting.</strong></p><p class="MsoNormal"><span style="font-size: 10pt;">Don’t insert programlisting into para tags, it causes damaged code on a page. </span></p><p class="MsoNormal"><strong><br/></strong></p><strong>12. JIRA issues format.</strong><p class="MsoNormal"><span style="font-size: 10pt;">All your tasks in JIRA should have versions and components defined. <br/></span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><strong>13. Image canvas size.</strong></p><p class="MsoNormal"><span style="font-size: 10pt;">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.</span></p></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-14255">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>