[jboss-user] [JBoss Tools] - Documentation notes

[Administrator Administrator]

Administrator Administrator [http://community.jboss.org/people/admin] modified the document:

"Documentation notes"

To view the document, visit: http://community.jboss.org/docs/DOC-14255

--------------------------------------------------------------
← back to  ../../docs/DOC-14250 How to write documentation for JBDS and JBoss Tools 
 
*1. Project structure schema.*
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 sudo apt-get install tree command will install this utility. You need to create the project structure schema in Linux since the tree command in Windows draws a tree that is not as nice as the one in Linux, besides Linux is our primary OS. However if you still need to draw a tree in Windows please use the tree /a /f command. This is what the project structure should be like.

|-- pom.xml
`-- src
    |-- main
    |   |-- java
    |   |   `-- org
    |   |       `-- docs
    |   |           `-- richfaces
    |   |               `-- Bean.java
    |   |-- resources
    |   `-- webapp
    |       |-- WEB-INF
    |       |   |-- faces-config.xml
    |       |   `-- web.xml
    |       |-- index.jsp
    |       `-- pages
    |           |-- index.jsp
    |           `-- index.xhtml
    `-- test
        `-- java
            `-- org
                `-- docs
                    `-- richfaces
                        `-- BeanTest.java

*2. Inline graphics scale - 100%.*
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. 

*3. Doc build process speed up.*
Command line option for only creating part of the outputs to speed up roundtrip
See the issue for details https://jira.jboss.org/jira/browse/MPJDOCBOOK-7

*4. Task reviewing.*
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. 

*5. Text validation.*
E.g.  letter “p” inside two opening tags (<section>p <title>… ) makes  the document invalid and failes the build on this place. Do not forget to validate xmls each time you make changes.

*6. JBDS team. movies update.*
When updating the guides according to some dev issue, remember about our movies collection, it also should be updated. 

*7. Inline graphics.*
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:
 
        <inlinemediaobject>   
             <imageobject>
                 <imagedata fileref="images/image1.png"/>
             </imageobject>
          </inlinemediaobject>

 *8. Task resolving before a release.*   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
When you’re resolving a task, make sure that the person who will be closing the task, has enough time for its verification. 
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’t have time to fix the task if it’s reopened. 

*9. "Fix version" of a jira issue.*
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.

*10. JIRA issues resolution.*
When closing an issue, plz write some resolution as the last comment about what exactly was done.

*11. Para and programlisting.*
Don’t insert programlisting into para tags, it causes damaged code on a page. 
*
*
*12. JIRA issues format.*All your tasks in JIRA should have versions and components defined. 


*13. Image canvas size.*
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.
--------------------------------------------------------------

Comment by going to Community
[http://community.jboss.org/docs/DOC-14255]

Create a new document in JBoss Tools at Community
[http://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2128]
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/jboss-user/attachments/20110124/de2d0310/attachment-0001.html