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