[JBoss JIRA] (TOOLSDOC-492) Create new docs landing page on new tools.jboss.org site (moving to asciidoc for docs in process)
2:32 a.m.
[
https://issues.jboss.org/browse/TOOLSDOC-492?page=com.atlassian.jira.plug...
]
Max Rydahl Andersen commented on TOOLSDOC-492:
----------------------------------------------
I'm all for moving from docbook to asciidoc but afaik the big showstopper is red hat
docs saying they must be in in docbook. If that has changed then lets go, but if not then
not much fun.
About putting docs *physically* on tools.jboss.org then my intent was to actually *not*
put it there since it would increase the build time significantly - but that was when it
was slow. Anyhow - putting it on docs.jboss.org with redirects might be a good option and
just keep the style.
a) Yes, many users uses pdf for sure to download and HTML is definitely needed.
b) freemarker is not dead. neither is the usage of portal in older versions.
c) should only be done for new versions for sure.... put it on docs.jboss.org where we can
have multiple versions properly layed out that does not require rebuilds again and again.
d) yes it mostly works - I tried others in past, I can dig them out if oreilly's
doesn't work. Others in the company done this already too.
e) filenames aren't used for categorize content by milestone afaik. whatsnew approach
doesn't fit userguides workflow IMO.
f) not sure what is asked for here - the downloads overview page is not about docs, but
yes docs could be linked to from the individual download pages but since there was no
decent structure for docs we could use we didn't for now.
I would like docs to move to asciidoc but mixingt that up *into* the website generation is
not the right way to do this.
Create new docs landing page on new tools.jboss.org site (moving to
asciidoc for docs in process)
-------------------------------------------------------------------------------------------------
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/scen... 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/documentatio...
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
4357
days inactive
4357
days old
jbosstools-issues@lists.jboss.org
0 comments
1 participants
participants (1)
-
Max Rydahl Andersen (JIRA)