OLga Chikvina [
http://community.jboss.org/people/Ochikvina] modified the document:
"How to Write Documentation for JBDS and JBoss Tools"
To view the document, visit:
http://community.jboss.org/docs/DOC-14250
--------------------------------------------------------------
**
#Places_of_main_doc_team_resources Places of main doc team resources
**
#Documentation_building_procedure Documentation building procedure
**
#Doc_JIRA Doc JIRA
**
#JBoss_ToolsJBDS_Demos JBoss Tools/JBDS Demos
**
#JBoss_ToolsJBDS_guides_structure JBoss Tools/JBDS guides structure
**
#Project_structure_schema Project structure schema
**
#Inline_graphics_scale__100 Inline graphics scale - 100%
**
#Doc_build_process_speed_up Doc build process speed up
**
#Task_reviewing Task reviewing
**
#Text_validation Text validation
**
#JBDS_team_movies_update JBDS team movies update
**
#JBDS_Inline_graphics JBDS Inline graphics
**
#Task_resolving_before_a_release Task resolving before a release
**
#JIRA_issues JIRA issues
**
#Para_and_programlisting Para and programlisting
**
#Image_canvas_size Image canvas size
**
#Docs_releasing_procedure Docs releasing procedure
***
#Using_diffmk_to_add_updatedadded_markers_to_TOC Using diffmk to add updated/added
markers to TOC
**
#Nightly_docs Nightly docs
h2. *Places of main doc team resources*
Here is the list resources related to JBDS/Tools docs:
1. SVN -
https://svn.jboss.org/repos/jbosstools/trunk
https://svn.jboss.org/repos/jbosstools/trunk
* doc folder with guide/guides is placed in plugin folder e.g.
https://svn.jboss.org/repos/jbosstools/trunk/esb/docs
https://svn.jboss.org/repos/jbosstools/trunk/esb/docs
*
https://svn.jboss.org/repos/jbosstools/documentation/trunk/movies
https://svn.jboss.org/repos/jbosstools/documentation/trunk/movies - folder with movies on
Tools and JBDS
*
https://svn.jboss.org/repos/jbosstools/trunk/documentation
https://svn.jboss.org/repos/jbosstools/trunk/documentation - folder with doc resources and
several guides.
— guides folder contains guides
— jbds-docs folder is the place to generate JBDS release docs -jbosstool-docbook-xslt -
xslt styles -jboss-tools-docs folder is the place to generate JBDS release docs
-jboss-tools-docs-architype - architype for new guides creation -jbosstool-jdocbook-style
-css styles
— qa folder with qa resources (qa owns it)
— whatsnew folder with what's new pages (dev team own it)
2. Doc project page contains links to release docs, nightly docs, movies —
http://jboss.org/tools/docs.html http://jboss.org/tools/docs.html
* NEWS - owned by dev team
* reference guides - release guides updated by us
* screen casts - movies we have made
* FAQ - owned by dev team
3. Doc JIRA for both tools and jbds doc projects is on jbds project JIRA —
https://jira.jboss.org/jira/browse/JBDS https://jira.jboss.org/jira/browse/JBDS
* open components tab - here is a list of components, doc component are ones with Doc-
prefix.
h2. *Documentation building procedure*
Here is an article on documentation building procedure
http://jboss.org/community/wiki/BuildingJBossToolsDocumentaion
http://jboss.org/community/wiki/BuildingJBossToolsDocumentaion
Read it and try to build the docs with different profiles from here
https://svn.jboss.org/repos/jbosstools/trunk/documentation
https://svn.jboss.org/repos/jbosstools/trunk/documentation
h2. *Doc JIRA*
Here is JBDS JIRA -
https://jira.jboss.org/jira/browse/jbds
https://jira.jboss.org/jira/browse/jbds
On the Open Issues 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.
Most of the issues that affects docs can be found in JBoss Tools JIRA -
https://jira.jboss.org/jira/browse/JBIDE https://jira.jboss.org/jira/browse/JBIDE. When a
doc task is created basing on a dev task, the tasks are linked to each other with "is
related to" link.
h2. *JBoss Tools/JBDS Demos*
* When making a demo, in its setting choose the necessary *jboss preloaders* and our
standard palette and save the movie with this settings, before committing it to svn.
* When making a demo, first of all *set 0,20 sec.* for all frames and then adjust the time
you need for some particular frames.
* When it’s necessary to draw *user attention* to some particular element on a frame, use
red ellipse (for small elements – tabs, buttons, etc.) or rectangle (for file lists,
windows, etc.)
* When a demo is done, watch it yourself and make sure that you have *enough time to read*
text in hints.
* When making a demo, make sure that you chose the *appropriate size for hint boxes*: not
lot’s of empty space should be under the text and the box should look like all other ones,
undamaged, ‘cause when you try to minimize it, it could change its form unproportionally,
try to avoid such an effect, minimize the box till its form (not size) remains the same.
* When making movie, make sure your *Wink uses* the elements from here, copy it to you
wink folders.
https://svn.jboss.org/repos/jbosstools/documentation/trunk/movies/common_...
* When creating a new movie please *use the style features* located here -
https://svn.jboss.org/repos/jbosstools/documentation/trunk/movies/common_...
* When creating demos make sure that you use correct *jboss.org styles*, time capture rate
is more or equal 4, and the cursor is moving smoothly on the screen
* When making a demo, make sure that all application forms, hints, windows are *not cut*
with demo frame.
e.g. the hint is cut
http://community.jboss.org/servlet/JiveServlet/showImage/102-14255-3-1596...
http://community.jboss.org/servlet/JiveServlet/downloadImage/102-14255-3-...
h2. *JBoss Tools/JBDS guides structure*
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):
1. Introduction
1.1. What is JBoss Portal and Portlet Tools?
1.2. Key Features of JBoss Portlet Tools
1.3. Requirements and Installation
2. JBoss Portlet Tools Tasks
2.1. Creating and Deploying a Java Portlet
2.1.1. Creating a Web Project with JBoss Portlet Capabilities
2.1.2. Adding a Java Portlet to a Web Project
2.1.3. Deploying a Portlet to JBoss Portal
2.2. Creating and Deploying a JSF Portlet
2.2.1. Creating a JSF Project with JSF Portlet Capabilities
2.2.2. Adding a JSF Protlet to the Project and Deploying It to JBoss Portal
2.3. Creating and Deploying a Seam Portlet
2.3.1. Creating a Seam Project with Seam Portlet Capabilities
2.3.2. Adding a Seam Protlet to the Project and Deploying It to JBoss Portal
3. Reference
3.1. JBoss Portlet Descriptors
3.2. Wizards
3.2.1. Java Portlet Wizard
3.2.2. JSF/Seam Portlet Wizard
3.3. JBoss Portlet Preferences
4. Summary
4.1. Other Relevant Resources on the Topic
*
*
*Comments:*
* 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.
* The "Requirements and Installation" section should provide minimal
requirements on the environment the plugin needs and installation procedure (or reference
to it).
* All procedural operations must be put into the "[plugin name] Tasks" chapter.
Each section of the chapter is a tutorial on a particular topic.
* The referential data should be stored in the "Reference" chapter.
* Remember to summarize the results and provide the links to other relevent resources in
the "Summary" chapter.
h2. *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
h2. *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.
h2. *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
https://jira.jboss.org/jira/browse/MPJDOCBOOK-7
h2. *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 your task.
h2. *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.
h2. **JBDS team movies update**
When updating the guides according to some dev issue, remember about our movies
collection, it also should be updated.
h2. *JBDS 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>
h2. *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.
h2. *JIRA issues*
*JIRA issues format.*
All your tasks in JIRA should have versions and components defined.
*JIRA issues resolution.*
When closing an issue, plz write some resolution as the last comment about what exactly
was done.
*"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.
h2. *Para and programlisting*
Don’t insert programlisting into para tags, it causes damaged code on a page.
h2. *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.
h2. *Docs* releasing procedure
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.
h3. *Using diffmk to add updated/added markers to TOC*
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.
We added two script files in the bin folder of the DiffMk distribution:
* run.sh
* run_mkdiff.sh.
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 [+the path to the file+] [+the path to the file
modified+] [+the path to the output file+]
To identify the changes between two different revisions of the same guide, use the
following line: ./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
Next, run the run_mkdiff.sh
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:
* It removes the HTML entities when outputs the file, for instance & in the
links;
* Sometimes it mixes the structure of the document, for instance, put the <chapter>
into the <chapter>;
* Sometimes it deletes the tags such as <imageobject>.
Thus, in order to build the docs with diff markers, the next step is validating and
checking the master_output.xml files carefully.
When the check and validation is done the next step you have to do is to build
documentation bundle with updated/new markers on the TOC and required styles.
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 JBDS doc release bundle,please, use
"releaseJBDS" profile,othervise
"release" profile meets your needs.
You can build release guides one by one using
mvn clean install -P releaseJBDS
or
mvn clean install -P release
maven command and then collect all the docs together.
But the least time-consuming method is to build the whole bundle from
+jbosstools_trunk\documentation\jboss-tools-docs+ directory using
mvn assembly:assembly -P releaseJBDS
or
mvn assembly:assembly -P release
maven command.After it all the guides will be built and collected in +en/+ folder.
+Note,that *eclipse* guides' versions should be excluded from the final version of the
bundle.+
In the end the created release bundle should be uploaded to the site.
JBDS release documentation should be placed
here:http://www.redhat.com/docs/en-US/JBoss_Developer_Studio/
while JBT release documentation should be here:
http://docs.jboss.org/tools/.
h2. *Nightly docs*
Nightly docs online:
http://download.jboss.org/jbosstools/nightly-docs/
http://download.jboss.org/jbosstools/nightly-docs/
Here is svn for it:
https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-docs
https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-docs
Here is Hudson for it:
http://hudson.qa.jboss.com/hudson/job/jbosstools-docs-nightly/
http://hudson.qa.jboss.com/hudson/job/jbosstools-docs-nightly/ (to build nightly docs VPN
access and admin pass are required)
When a new guide is created it should be added to nightly docs build
* add it to pom.xml:
https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-do...
https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-do...
https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-do...
https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-do...
* add it to all-guides.xml:
https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-do...
https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-do...
* add it to the index.html (master.xml) page:
https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-do...
https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-do...
See that the guide is added and email Denis Golovin asking to add a new guide to the
server settings for nightly docs.
Build the guides with mvn clean install from
https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-docs
https://svn.jboss.org/repos/jbosstools/trunk/documentation/jboss-tools-docs
http://community.jboss.org/docs/DOC-14252 Places of main Docteam resources
--------------------------------------------------------------
Comment by going to Community
[
http://community.jboss.org/docs/DOC-14250]
Create a new document in JBoss Tools at Community
[
http://community.jboss.org/choose-container!input.jspa?contentType=102&am...]