juneau-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Craig Russell <craig.russ...@oracle.com>
Subject Re: Summary of websites.
Date Sun, 07 Aug 2016 21:16:45 GMT
Caveat: I haven’t spent too much time thinking about these issues. But here goes.

>>> Main website - *http://juneau.incubator.apache.org/

This will become http://juneau.apache.org after graduation, and should be the canonical entry
point to everything Juneau. 

> On Aug 7, 2016, at 12:06 PM, James Bognar <james.bognar@salesforce.com> wrote:
> 
> I think in general, everything should be accessible from the website, but
> developer content can be kept in wikis?  I just assume it's going to be
> easier to write and maintain wikis for stuff like workspace setup docs?

I agree wikis are nice. It’s easier than maintaining formal documentation as part of the
source tree, but it isn’t free either. The dev team will need to organize (and reorganize)
the wiki to keep some semblance of order. It’s also a good way to allow folks to contribute
without the hassle of pull requests or granting commit access.
> 
>> I would recommend using maven-scm-publish to push to git after a build.
>> Likewise come up with a release process.

> 
> Is it still okay that we're storing Javadocs in git?  I don't know much
> about git internals, but my fear is that every time we build and publish
> the javadocs, we're creating another copy of all those files in git.  It's
> 38MB.  Someone might get mad at us for our repo increasing in size by 38MB
> every day :-)

I don’t think source repositories should be used to store generated content. Just as source
repos should not store binaries. It should be trivial to generate javadocs by normal mvn targets
after the code is downloaded into your own local copy. 

But it’s also good to maintain a current copy of javadocs available on the web site for
folks who want a reference without necessarily downloading the code and generating themselves.


I like James’s proposal:

> *Javadocs -*
> http://juneau.incubator.apache.org/api-documentation/index.html
> 
> We keep all of our user documentation in the Javadocs (overview.html and
> package-level HTML files). 

With a high level link from the juneau.incubator.apache.org page to “Documentation”. 

Craig
> 
> 
> 
> On Sun, Aug 7, 2016 at 12:53 PM, John D. Ament <johndament@apache.org>
> wrote:
> 
>> I'm a bit confused.  Is this meant to be current state or future state?
>> 
>> On Sun, Aug 7, 2016 at 12:30 PM James Bognar <james.bognar@salesforce.com>
>> wrote:
>> 
>>> Hi all,
>>> 
>>> Here's a summary of our websites and their purposes.
>>> 
>>> 
>>> *Main website - *http://juneau.incubator.apache.org/
>>> 
>>> A very basic page with a quick summary and links.  Try to keep this
>> sparse
>>> (i.e. no knowledge articles, developer info, etc...).
>>> 
>>>   - https://issues.apache.org/jira/browse/JUNEAU-6 - Complete project
>>>   website.
>>>   Current page was put together quickly and needs to be cleaned up.
>>> 
>>> 
>> It should be the goal that juneau.i.a.o is the canonical home page and
>> source of all things Juneau.  It may link to other resources, but as much
>> as possible should go here IMHO.
>> 
>> 
>>> 
>>> *Javadocs -*
>>> http://juneau.incubator.apache.org/api-documentation/index.html
>>> 
>>> We keep all of our user documentation in the Javadocs (overview.html and
>>> package-level HTML files).  "Articles" can be written as HTML files in
>>> doc-files directories.
>>> 
>>>   - https://issues.apache.org/jira/browse/JUNEAU-10 - This is currently
>>>   hosted by dumping the generated Javadocs into
>>>   *incubator-juneau-website/content/api-documentation*.  It feels wrong
>>>   storing generated Javadocs in a git repo.  Is there a better option
>> for
>>>   hosting javadocs?
>>> 
>> 
>> I would recommend using maven-scm-publish to push to git after a build.
>> Likewise come up with a release process.
>> 
>> 
>>> 
>>> 
>>> *Incubator website -* http://incubator.apache.org/projects/juneau.html
>>> 
>>> Really nothing of substance should be on this page except
>>> incubation-related info.
>>> 
>>>   - https://issues.apache.org/jira/browse/JUNEAU-8 - The data in the
>>>   Project Info section should all be moved to the main website, and
>>> Incubator
>>>   information needs to be updated.
>>> 
>>> 
>>> *GitHub mirror - *http://github.com/apache/incubator-juneau
>>> 
>>> This mirror page is populated with data from the README.md in the source
>>> code root.  Maybe just replace the contents with a link to the main
>>> website?
>>> 
>>>   - https://issues.apache.org/jira/browse/JUNEAU-5 - Update root
>>> README.md
>>>   file.
>>> 
>>> 
>>> *Confluence workspace -*
>>> https://cwiki.apache.org/confluence/display/JUNEAU/Juneau+Home
>>> 
>>> All developer-related information should be kept here:
>>> - Instructions on workspace setup
>>> - Instructions on becoming contributors
>>> - Design documents
>>> 
>>>   - https://issues.apache.org/jira/browse/JUNEAU-7 - Set up Confluence
>>>   workspace.
>>> 
>>> 
>> Mmm this I'm iffy on.  We can have this hosted in confluence, or on the
>> website.  Make sure the linking is bi-directional.  Its good to host
>> designs in confluence.  The community aspects though I would hope are on
>> the main website.
>> 
>> 
>>> 
>>> 
>>> 
>>> --
>>> James Bognar
>>> 
>> 
> 
> 
> 
> -- 
> James Bognar

Craig L Russell
clr@apache.org



Mime
View raw message