John D. Ament created DELTASPIKE-690:
----------------------------------------
Summary: 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.2#6252)
