8:33 a.m.
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-do...
https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-do...
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&am...]