[jira] [Commented] (DELTASPIKE-690) Documentation donation from RedHat
[
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 sent
[jira] [Commented] (DELTASPIKE-690) Documentation donation from RedHat
[ https://issues.apache.org/jira/browse/DELTASPIKE-690?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14134970#comment-14134970 ] Jason Porter commented on DELTASPIKE-690: - There was good documentation up on JDF, but it looks like we've lost it in the new JBoss.org, I'll create a ticket for that. In the mean time, feel free to use https://github.com/seam/migration/blob/develop/open18_migration.asciidoc > 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 m
[jira] [Commented] (DELTASPIKE-690) Documentation donation from RedHat
[ https://issues.apache.org/jira/browse/DELTASPIKE-690?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14239310#comment-14239310 ] Rafael Benevides commented on DELTASPIKE-690: - Staging documents from [~mmurray] at http://deltaspike.apache.org/staging/documentation/ > 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 add
