[jbosstools-issues] [JBoss JIRA] (TOOLSDOC-492) migrate JBT User Guide to adoc so it's easier to maintain and can be reskinned to match new websiite

[Nick Boldt (JIRA)]

Nick Boldt created TOOLSDOC-492:
-----------------------------------

             Summary: migrate JBT User Guide to adoc so it's easier to maintain and can be reskinned to match new websiite
                 Key: TOOLSDOC-492
                 URL: https://issues.jboss.org/browse/TOOLSDOC-492
             Project: Documentation for JBoss Tools and Developer Studio
          Issue Type: Bug
      Security Level: Public (Everyone can see)
          Components: User Guide
    Affects Versions: 4.2.0.Beta1
            Reporter: Nick Boldt
            Assignee: Michelle Murray
             Fix For: 4.2.0.Beta2


With the release of the new tools.jboss.org site, it's time to migrate the docs to the same skin / format / markup. Docbook is dead, long live Asciidoc!

What [~mmurray] and I are thinking is that we would have a new landing page similar to one of these:

http://tools.jboss.org/features/ (with icons that link to projects' latest doc)
or
http://tools.jboss.org/documentation/whatsnew/ (with the latest doc linked)

And then under that landing page we'd have doc for each of projects' contributions to the User Guide, by milestone or Final release.

Questions:

a. [~maxandersen] [~burrsutter] [~mmusaji] Do we still need to provide 3 formats of doc - HTML, HTML-single, and PDF? Or can we replace that with this new content, PLUS include inline help doc within Eclipse? (That's another issue - see [~dgolovin] 's https://github.com/dgolovin/jbosstools-eclipse-docs/blob/master/docs/scenarios.md for prototype)

b. [~maxandersen] Should we include docs for "dead" projects like Freemarker, Portal, etc.? I'm guessing YES, even if the doc becomes out of date (ie., the doc for JBT 4.2 for Freemarker won't have changed much (or at all) since JBT 4.0/4.1).

c. [~maxandersen] Should we convert old JBT 4.1.x (and/or 4.0.x, 3.3.x) doc to the new adoc format, or just start w/ the JBT 4.2.0.Beta1/2 doc? I'd be OK with 4.1 and maybe 4.0, but can we skip 3.3 since JBDS 5 is no longer fully supported?

d. Will docbook2asciidoc [0] work for batch-converting docbook docs to adoc? @nick will try. If conversion works easily, then converting older User Guides is definitely more doable / less time consuming.

[0] https://github.com/oreillymedia/docbook2asciidoc

e. [~xcoulon] Is :page-component_version: still used, eg., in [1], or is the filename version itself used to categorize the content by milestone?

[1] https://github.com/jbosstools/jbosstools-website/blob/master/documentation/whatsnew/openshift/openshift-news-2.6.0.Beta1.adoc

f. If we decide to continue to include other formats (eg., html-single, pdf) should we link to those from these places [2], [3]?

[2] http://tools.jboss.org/downloads/overview.html
[3] http://tools.jboss.org/downloads/jbosstools/luna/4.2.0.Beta1.html

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira