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