[weld-issues] [JBoss JIRA] Created: (WELD-414) Make Weld docs available for JBoss AS 6

[Pete Muir (JIRA)]

Make Weld docs available for JBoss AS 6
---------------------------------------

                 Key: WELD-414
                 URL: https://jira.jboss.org/jira/browse/WELD-414
             Project: Weld
          Issue Type: Task
          Components: Documentation
            Reporter: Pete Muir
            Assignee: Dan Allen
            Priority: Critical
             Fix For: 1.0.2.CR1


Magnolia is the tool we use to build out the JBoss community site.  Please take a moment and go to http://www.jboss.org/author.
Username: **********
Password: **********

Scroll down and open jbossas --> docs --> 6-x
Highlight 6-x and press the "Open page..." button at the bottom.  The main AS6 docs page will open in another tab or window.

>From here you can see how AS6 documentation will be broken up into "Core" and "Component".  Click on the "JavaServer Faces (JSF)" link  You'll get an idea of what you can do with your section.

As you can see, we want to provide something beyond the DocBook documentation we've had in the past.  We want a developer to be able to come to the docs section and find everything he might need to work with a particular part of AS6, including spec info, javadoc, sample code, and links to other info.

Of course, we don't want to fork the stuff we already have but we also need to recognize that developers want to use AS6 as a single product and they come to AS6 with an "AS6" mindset.  So they are thinking, "How do I use the EJB features built into AS6?" or "How do I use the Weld framework built into AS6?".  We need to provide documentation that answers those questions from an AS6 point of view. But I'm using the word "documentation" in a loose sense.  It doesn't have to be a single document.  The aggregation of AS6 information is done with Magnolia and not necessarily with a single DocBook monograph.

I am assuming that most components will have at least some AS6-specific content that needs to go somewhere.  If it's possible/practical to use Maven profiles to pull in special content and create an AS6 version of a document then that would be best.  If not, then AS6-specific content could be put into its own small document.  The rest can be referenced with links to the component's project documentation.

As for where the doco lives in what part of SVN, I don't think that it really matters.  I like the idea that each component team is responsible for handling their section however is most practical for them.  I just want to make sure that at the end of the day an AS6 user has everything he needs in a way that is easy to find and understand.

Action items for you:
* Take a look at http://jboss.org/help/projectpageguide.html to learn about Magnolia.
* Find the section on Weld and start building out the page(s)
* Work out how best to incorporate the Weld ref guide into the JBoss AS docs
   - remove irrelevant sections
   - apply JBoss AS styling

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: https://jira.jboss.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira