[
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
