[ 
https://issues.apache.org/jira/browse/DELTASPIKE-690?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14134952#comment-14134952
 ] 

Michelle Murray commented on DELTASPIKE-690:
--------------------------------------------

Regards migration instructions, from https://issues.jboss.org/browse/WFKDOC-108

{quote}
Robert Reimann added a comment - 6 days ago
Missing Seam2 and Seam 3 info - are these both still relevant?
We're currently experiencing serious issues while trying to migrate Seam2 and 
Seam3 applications from JBoss AS7 to WildFly 8. Given the fact that Seam2/3 is 
discontinued and recommends DeltaSpike as migration target it would be very 
much appreciated to have some documentation/examples in place for that kind of 
migration scenarios.
{quote}

> Documentation donation from RedHat
> ----------------------------------
>
>                 Key: DELTASPIKE-690
>                 URL: https://issues.apache.org/jira/browse/DELTASPIKE-690
>             Project: DeltaSpike
>          Issue Type: Improvement
>          Components: Documentation
>            Reporter: John D. Ament
>            Assignee: Rafael Benevides
>
> DeltaSpike Doc Reorg Proposal
> Summary of task
> Develop better structure of docs so users can find required info
> https://issues.apache.org/jira/browse/DELTASPIKE-642
> Areas identified for improvement
> 1. Presentation
> The Documentation page of the DeltaSpike site provides a long linked table of 
> contents. The links in the table of contents take users to the relevant 
> section of the document lower down the page but for a number of these 
> sections the user then needs to click another link to get to the actual 
> content (e.g., Core).
> Examples are listed as the very last item of the Documentation page (and also 
> listed on the Home page).
> Migration information appears to be linked from the menu bar only.
> Recommendations
> Change the landing Documentation page to solely provide a list of categorized 
> (and linked) titles, keeping the actual content on separate pages. [For 
> example, http://aerogear.org/docs/guides/]
> Arrange the titles under four categories as follows:
> Getting Started
> Overview of DeltaSpike
> Installing and Configuring DeltaSpike
> Migrating to DeltaSpike
> Examples and Tutorials
> Using Individual Modules
> Link for each module page
> Reference
> Build DeltaSpike from Source
> API
> SPI
> More Resources
> Blogs and Articles
> Add-ons
> External Examples
> 2. Organization
> Lots of sections contain solely a link to another section or the sole link to 
> another page. An example of the latter is the Project Configuration without 
> Maven page, in which the in-text hyperlinked ‘build’ provides the only link 
> to the Building DeltaSpike from Source page. This kind of organization means 
> that users can get easily lost navigating the documentation and makes it 
> harder for users to understand quickly how concepts and components fit 
> together.
> Recommendations
> Implement the presentation changes recommended in item 1, which links every 
> page from the Documentation page and provides a logical structure to the 
> content.
> Within each page, structure the content as outlined in the page tables at the 
> end of this document.
> 3. Examples and Tutorials
> The existing Examples page is low on detail.
> There is one (internal) DeltaSpike example listed (artifact-id: 
> deltaspike-jse-owb-example) but no details on how to obtain or build it. A 
> number of examples are distributed as part of source.zip but their existence 
> is not advertised on the website. The distributed examples do not have README 
> files to inform users what the examples are or how to use them. Several 
> project templates in GitHub are linked from the Documentation page but no 
> information is provided about them. These project templates do not have 
> README files to inform users what the templates are or how to use them.
> The list of external DeltaSpike examples is minimal and the user has to open 
> every link to find out more about each. Further, some of the examples linked 
> here contain no README file to instruct users what the example is or how to 
> build it.
> There are no quickstart tutorials. It difficult for a user to quickly 
> understand or experience adding DeltaSpike to a sample project or their own 
> project and assess whether they want to learn more about DeltaSpike.
> Recommendations
> Expand the information provided on the currently listed internal example, 
> including information on what the example demonstrates and how to build it.
> Add 2-3 sentences about each of the examples distributed in source.zip, 
> specifying that the examples source is available in source.zip.
> Add a README file to the source code for each distributed example in 
> source.zip.
> Add 2-3 sentences about each of the project templates.
> Add a README file to the source code for each project template in GitHub.
> Provide one sentence about each of the external project links - what the 
> project is a demonstration of, why/when would the user find the example 
> helpful.
> Put together a simple tutorial either:
>  a) demonstrating how to add (for example) the DeltaSpike Core module to a 
> maven project and make use of one of the main module features in the project.
> b) pulling apart the code of one of the project templates, pointing out where 
> DeltaSpike has been added and what its inclusion achieves.
> This would advertise how simple DeltaSpike is to use and the awesomeness of 
> one of the DeltaSpike Core module features.
> 4. API
> Some limited API information is provided but standard API docs are missing. 
> For example, see the CDI API at http://docs.jboss.org/cdi/api/1.0/
> Recommendations
> Code in all modules should be annotated so that API docs can be autogenerated.
> API docs should be hosted on the DeltaSpike website and distributed in the 
> DeltaSpike .zip file.
> 5. Writing Style
> There are language errors within the documentation.
> Recommendations
> All content needs reviewing and editing for language errors.
> Proposed structure of each page
> Getting Started Content
> Overview of DeltaSpike
> (1 page)
> Background: Portable CDI Extensions
> About DeltaSpike
> Features of DeltaSpike
> Use Cases of DeltaSpike
> Most of the content for this is in the existing Introduction but needs 
> rechunking:
> https://deltaspike.apache.org/documentation.html#introduction
> Use cases text (extended scenario of type of app that could benefit from 
> DeltaSpike) is missing
> Installing and Configuring DeltaSpike
> (1 page)
> System Requirements [If any?]
> Using DeltaSpike with Maven
> Using DeltaSpike without Maven
> Adding a Server or Servlet Container CDI Implementation
> System Requirements info is missing [Are there any? Java EE or SE, 
> preinstalled CDI version?, Maven version?]
> https://deltaspike.apache.org/documentation.html#deployment-mode
> Adding DeltaSpike to Maven Projects
> (1 page)
> Configuring the Project pom.xml
> Adding the Core Module Dependency
> Adding the Option Module Dependencies
> Testing Snapshots 
> Configuring further when using Java SE
> Adding the Container Control Module and CDI Container Dependencies
> Starting a CDI Container
> Using DeltaSpike Features
> https://deltaspike.apache.org/documentation.html#getting-started
> Would prefer to put config info for individual modules on the page of each 
> module
> https://deltaspike.apache.org/documentation.html#start-a-cdi-container-using-java-se
> For using DS features, just include links directing users to see individual 
> module pages and the examples and tutorials page(s)
> Migrating Projects to DeltaSpike
> (1 page)
> Apache MyFaces CODI to DeltaSpike
> JBoss Seam2 to DeltaSpike
> JBoss Seam3 to DeltaSpike
> https://deltaspike.apache.org/migration-guide.html#introduction
> Missing any Introduction text
> For each migration scenario:  migration motivation/benefits of DeltaSpike, in 
> general what needs changing and why, use an example (inc. code snippets) to 
> demonstrate the changes introduced in migrating an application
> MyFaces CODI example needs fleshing out
> Missing Seam2 and Seam 3 info - are these both still relevant?
> Tutorials and Examples
> (1 or 2 pages if tutorial is long)
> Examples
> Project Templates
> Tutorial
> https://deltaspike.apache.org/examples.html
> As outlined in item 3.
> Examples here are just the distributed ones - detail external ones later in 
> More Resources section.
> Using Individual Modules content
> Module list with Core first and optionals listed alphabetically, one page for 
> each module
> Core (required)
> Bean Validation (optional)
> Container Control (optional)
> Data (optional)
> JPA (optional)
> JSF (optional)
> Partial-Bean (optional)
> Scheduler (optional)
> Security (optional)
> Servlet (optional)
> Test-Control (optional)
> As far as possible, each module page should follow a common template:
> About Module (an overview)
> Specifying the Module Dependencies for Maven Projects
> Configuring for Specific Servers and Servlet Containers
> Module Features - group features in appropriate categories based on module, 
> each feature backed with an example code snippet (most already are); Provide 
> the path (where appropriate, e.g., from a quickstart) and filename for each 
> code snippet.
> Seeing the Module in Action - details/links of internal/external examples + 
> project templates showing module in use
> More Resources - details/links to blogs, articles, API which may be of use to 
> the user in using/understanding the module
> Reference Content
> Build DeltaSpike from Source
> (1 page)
> https://deltaspike.apache.org/build.html
> SPI
> (1 page)
> https://deltaspike.apache.org/spi.html
> API
> (1 page)
> For details see item 4.
> More Resources Content
> (1 page)
> Blogs and Articles
> Extend list of blogs, add links to some individual blog posts or articles 
> that really stand out
> Add-ons
> Missing an explanation of what add-ons are
> Provide 2-3 sentences about each add-on, what it is, what it achieves, how to 
> add to project
> External Examples
> https://deltaspike.apache.org/examples.html
> List external examples only and improve as detailed in item 3.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

Reply via email to