[jira] [Commented] (DELTASPIKE-690) Documentation donation from RedHat

["Michelle Murray (JIRA)" <ji...@apache.org>]

    [ 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)