[prev in list] [next in list] [prev in thread] [next in thread] 

List:       openejb-development
Subject:    Re: Documentation site
From:       David Jencks <david.a.jencks () gmail ! com>
Date:       2020-02-09 20:26:00
Message-ID: F21CE8ED-F764-4280-A885-F488F7600D85 () gmail ! com
[Download RAW message or body]


Possibly there's some duplication in the new site:

individual addresses in sitemaps, without translations:
old sitemap page count: 560 old-sitemap-addr.txt
new sitemap page count: 1423 new-sitemap-addr-en-only.txt

comparison of unique page names (without path, source, or version info):
old-not-new count: 1 old-not-new-index.txt
new-not-old count: 119 new-not-old-index.txt

If anyone has ideas how to identify it, I'd like to hear them.

Is the live-site sitemap actually accurate?

thanks
David Jencks

> On Feb 9, 2020, at 11:55 AM, David Jencks <david.a.jencks@gmail.com> wrote:
> 
> I think I've found all the existing content sources and incorporated them in to the \
> Antora-built site. 
> Sources:
> 
> * tomee  docs (moved to antora structure) (versions master = 8.0, 7.1, and 7.0)
> * tomee examples (script to copy/rename to antora structure for appropriate \
>                 language)  (version master = 8.0 only)
> * tomee-site-generator (converted to adoc and moved to antora structure) (currently \
>                 labeled version 0.1)
> * tomee-site (converted to adoc and moved to antora structure) (currently labeled \
> version 0.0) 
> Comparing the live site-map.xml and the ones generated for the Antora-built site, \
> there is one file missing (index-old.html        \
> http://tomee.apache.org/examples/index-old.html \
> <http://tomee.apache.org/examples/index-old.html>) which I don't think is necessary \
> or appropriate to move, and 119 new files that didn't appear in the existing site. \
> They are listed in tomee@antora docs/new-not-old-index.txt. 
> The old-new diffs are only whether some version of the file stem appears in each \
> site, I haven't tried to figure out how to compare which versions each page appears \
> in. 
> So far I've made no attempt to incorporate javadoc.
> 
> If you are not quite familiar with Antora structure looking at the preview at \
> https://tomee-preview.s3-us-west-2.amazonaws.com/index.html \
> <https://tomee-preview.s3-us-west-2.amazonaws.com/index.html> will probably help \
> understand the questions.  In particular in the lower left corner there's the \
> "component drawer" where you can select the component and version to view. 
> Questions:
> 
> * How should the content be arranged into components and versions?
> 
> ** current state:
> 
> *** There are two components, tomee and examples.
> 
> *** The tomee component has versions 8.0, 7.1, and 7.0 (from tomee/docs) and 0.1 \
> (from tomee-site-generator) and 0.0 (tomee-site) 
> *** The examples component has versions 8.0-en, 8.0-sp, 8.0-pt for the different \
> languages 
> ** Sub-questions:
> 
> *** Is all of the content I've put under tomee actually version specific, or is \
> there some content that is conceptually unversioned (general information about \
> tomee, perhaps).  This could be separated into a separate unversioned component. 
> *** Is some or all of the content I've put in 0.1 and 0.0 actually associated with \
> a real version such as 1.7 or OpenEJB v??? 
> *** Is there a need to maintain earlier versions of the examples documentation, or \
> is just "current" enough?  It looks like there are earlier examples directories in \
> the 7.1.x and 7.0.x branches, and it would certainly be possible to convert them \
> and include them in the site, but I think that might make the site harder to use \
> and less informative. 
> * How should the content with a version be organized on the source tree and in the \
> navigation?  The source-tree questions certainly don't need immediate answers. 
> ** Source tree: Antora source structure is \
> modules/<module-name>/pages/<path-to-adoc>.  The ‘default' module name is \
> ‘ROOT', which is what I've used. Antora can deal directly with content in \
> subfolders of ‘pages' (some of which has appeared reflecting the original \
> arrangement) and additional modules (useful to keep each module a manageable size). \
>  
> *** To what extent would it be useful to break the content up into modules?
> 
> *** The examples are grouped in the navigation but are flat in the file system.  \
> Would it be appropriate to reflect the doc grouping in the file system layout? 
> ** Navigation current state:
> 
> *** The 8.0, 7.1, and 7.0 tomee versions have navigation adapted from \
> documentation.adoc This seems more or less reasonable for now. 
> *** The 0.1 and 0.0 tomee versions have navigation generated by just listing all \
> the pages. 
> *** The examples have navigation adapted from the existing examples navigation.
> 
> ** Sub-questions:
> 
> *** How should the 0.1 and 0.0 be organized? Is there an existing page that is a \
> starting point, as documentation.adoc is for more current content? 
> *** What other changes or refinements are appropriate?
> 
> ** Other:
> 
> *** can the conglomerated javadoc be generated by maven rather than the custom \
> script now used?  Starting with a javadoc jar seems simpler than building it as \
> part of the site generation. 
> =====
> Where is it?
> preview:  https://tomee-preview.s3-us-west-2.amazonaws.com/index.html \
> <https://tomee-preview.s3-us-west-2.amazonaws.com/index.html>  git repos:
> tomee <https://github.com/djencks/tomee> (antora, antora-tomee-7.1.x, \
> antora-tomee-7.0.x) Some instructions are in docs/INSTRUCTIONS.adoc \
> tomee-site-generator <https://github.com/djencks/tomee-site-generator> (antora) \
> tomee-site <https://github.com/djencks/tomee-site> (antora) 
> Thanks!
> 
> David Jencks
> 
> 
> > On Feb 8, 2020, at 10:32 PM, David Jencks <david.a.jencks@gmail.com \
> > <mailto:david.a.jencks@gmail.com>> wrote: 
> > I now have the adoc content from master, 7.1.0.x, 7.0.0.x, the example \
> > README.adoc from master (sorted by language), and the formerly .md files from \
> > tomee-site-generator. 
> > 
> <all the history snipped>



[prev in list] [next in list] [prev in thread] [next in thread]