[jira] [Commented] (DELTASPIKE-690) Documentation donation from RedHat
[ https://issues.apache.org/jira/browse/DELTASPIKE-690?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=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 added and what its inclusion achieves. This would advertise how simple DeltaSpike is to use and
[jira] [Commented] (DELTASPIKE-690) Documentation donation from RedHat
[
https://issues.apache.org/jira/browse/DELTASPIKE-690?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=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
[jira] [Commented] (DELTASPIKE-690) Documentation donation from RedHat
[ https://issues.apache.org/jira/browse/DELTASPIKE-690?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=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 module features in the project. b) pulling apart the code of one of the project templates,
