Documentation Contribution Opportunities

classic Classic list List threaded Threaded
23 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Documentation Contribution Opportunities

David Blevins-2
Hello hopeful contributors!

As of this weekend we have two new index pages for our documentation on the website:

 - http://tomee.apache.org/tomee-8.0/docs/
 - http://tomee.apache.org/tomee-8.0/examples/

The source for each of these index pages is generated by walking over each Markdown or Asciidoc file in these two sections of the main repo and looking for an `index-group=Foo` header in the document.  That's how they get grouped.

 - https://github.com/apache/tomee/tree/master/docs
 - https://github.com/apache/tomee/tree/master/examples

In the 'docs' directory alone there are 165 files that have "Unrevised" as the header or no header at all.  We need to get a header on all 165 of them.



If you're looking for a way to contribute, there are 165 of them right there.  At 15 minutes each document that's 2475 minutes or 41.25 hours of community work.

  ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^  ^   ^  ^  ^  ^

:)

What we need is each doc to be reviewed, checked for any formatting issues such as inconsistent h1, h2, h3 usage, then make your best guess on what the topic is (JavaMail, JMS, CDI, JPA, etc), then set that as the header `index-group=JMS` and submit a PR along with any updates to the document you think are good (maybe none at all)

Here's a couple sample commits:

 - https://github.com/apache/tomee/commit/bdee81d34c60644b755621254a535d0d8757eb21
 - https://github.com/apache/tomee/commit/e2190a47c211c870680d761efd6d025d935546c7


If you'd like to build the docs locally, run this long command and then open your browser to http://localhost:8080

 - git clone [hidden email]:apache/tomee-site-generator.git && cd tomee-site-generator && mvn clean compile -Djbake.http=true


On the formatting inconsistencies:

 - We use to use Confluence.  There are actually some pages still with that old format.
 - Some docs randomly start at h3 or h5.  They need to start at h1 and strictly not jump to h3 without an h2 in the middle.
 - If you have the energy to convert it from Markdown to Asciidoc, yay!

We need to do this for both the docs and examples.

 - https://github.com/apache/tomee/tree/master/docs
 - https://github.com/apache/tomee/tree/master/examples


--
David Blevins
http://twitter.com/dblevins
http://www.tomitribe.com

Reply | Threaded
Open this post in threaded view
|

Re: Documentation Contribution Opportunities

Matthew Broadhead-2
Hi David,
I would be happy to do this task.  But how to avoid conflicting PRs?
Matthew

On 03/12/2018 04:21, David Blevins wrote:

> Hello hopeful contributors!
>
> As of this weekend we have two new index pages for our documentation on the website:
>
>   - http://tomee.apache.org/tomee-8.0/docs/
>   - http://tomee.apache.org/tomee-8.0/examples/
>
> The source for each of these index pages is generated by walking over each Markdown or Asciidoc file in these two sections of the main repo and looking for an `index-group=Foo` header in the document.  That's how they get grouped.
>
>   - https://github.com/apache/tomee/tree/master/docs
>   - https://github.com/apache/tomee/tree/master/examples
>
> In the 'docs' directory alone there are 165 files that have "Unrevised" as the header or no header at all.  We need to get a header on all 165 of them.
>
>
>
> If you're looking for a way to contribute, there are 165 of them right there.  At 15 minutes each document that's 2475 minutes or 41.25 hours of community work.
>
>    ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^  ^   ^  ^  ^  ^
>
> :)
>
> What we need is each doc to be reviewed, checked for any formatting issues such as inconsistent h1, h2, h3 usage, then make your best guess on what the topic is (JavaMail, JMS, CDI, JPA, etc), then set that as the header `index-group=JMS` and submit a PR along with any updates to the document you think are good (maybe none at all)
>
> Here's a couple sample commits:
>
>   - https://github.com/apache/tomee/commit/bdee81d34c60644b755621254a535d0d8757eb21
>   - https://github.com/apache/tomee/commit/e2190a47c211c870680d761efd6d025d935546c7
>
>
> If you'd like to build the docs locally, run this long command and then open your browser to http://localhost:8080
>
>   - git clone [hidden email]:apache/tomee-site-generator.git && cd tomee-site-generator && mvn clean compile -Djbake.http=true
>
>
> On the formatting inconsistencies:
>
>   - We use to use Confluence.  There are actually some pages still with that old format.
>   - Some docs randomly start at h3 or h5.  They need to start at h1 and strictly not jump to h3 without an h2 in the middle.
>   - If you have the energy to convert it from Markdown to Asciidoc, yay!
>
> We need to do this for both the docs and examples.
>
>   - https://github.com/apache/tomee/tree/master/docs
>   - https://github.com/apache/tomee/tree/master/examples
>
>

Reply | Threaded
Open this post in threaded view
|

Re: Documentation Contribution Opportunities

Matthew Broadhead-2
In reply to this post by David Blevins-2
Should the licence be stored centrally and appended to the top (or
bottom) of each page?

On 03/12/2018 04:21, David Blevins wrote:

> Hello hopeful contributors!
>
> As of this weekend we have two new index pages for our documentation on the website:
>
>   - http://tomee.apache.org/tomee-8.0/docs/
>   - http://tomee.apache.org/tomee-8.0/examples/
>
> The source for each of these index pages is generated by walking over each Markdown or Asciidoc file in these two sections of the main repo and looking for an `index-group=Foo` header in the document.  That's how they get grouped.
>
>   - https://github.com/apache/tomee/tree/master/docs
>   - https://github.com/apache/tomee/tree/master/examples
>
> In the 'docs' directory alone there are 165 files that have "Unrevised" as the header or no header at all.  We need to get a header on all 165 of them.
>
>
>
> If you're looking for a way to contribute, there are 165 of them right there.  At 15 minutes each document that's 2475 minutes or 41.25 hours of community work.
>
>    ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^  ^   ^  ^  ^  ^
>
> :)
>
> What we need is each doc to be reviewed, checked for any formatting issues such as inconsistent h1, h2, h3 usage, then make your best guess on what the topic is (JavaMail, JMS, CDI, JPA, etc), then set that as the header `index-group=JMS` and submit a PR along with any updates to the document you think are good (maybe none at all)
>
> Here's a couple sample commits:
>
>   - https://github.com/apache/tomee/commit/bdee81d34c60644b755621254a535d0d8757eb21
>   - https://github.com/apache/tomee/commit/e2190a47c211c870680d761efd6d025d935546c7
>
>
> If you'd like to build the docs locally, run this long command and then open your browser to http://localhost:8080
>
>   - git clone [hidden email]:apache/tomee-site-generator.git && cd tomee-site-generator && mvn clean compile -Djbake.http=true
>
>
> On the formatting inconsistencies:
>
>   - We use to use Confluence.  There are actually some pages still with that old format.
>   - Some docs randomly start at h3 or h5.  They need to start at h1 and strictly not jump to h3 without an h2 in the middle.
>   - If you have the energy to convert it from Markdown to Asciidoc, yay!
>
> We need to do this for both the docs and examples.
>
>   - https://github.com/apache/tomee/tree/master/docs
>   - https://github.com/apache/tomee/tree/master/examples
>
>

Reply | Threaded
Open this post in threaded view
|

Re: Documentation Contribution Opportunities

brunobat
Hi

Do you mean, the Apache license in header on the top of each source file?

Cheers

Bruno Baptista
https://twitter.com/brunobat_


On 03/12/18 11:25, Matthew Broadhead wrote:

> Should the licence be stored centrally and appended to the top (or
> bottom) of each page?
>
> On 03/12/2018 04:21, David Blevins wrote:
>> Hello hopeful contributors!
>>
>> As of this weekend we have two new index pages for our documentation
>> on the website:
>>
>>   - http://tomee.apache.org/tomee-8.0/docs/
>>   - http://tomee.apache.org/tomee-8.0/examples/
>>
>> The source for each of these index pages is generated by walking over
>> each Markdown or Asciidoc file in these two sections of the main repo
>> and looking for an `index-group=Foo` header in the document.  That's
>> how they get grouped.
>>
>>   - https://github.com/apache/tomee/tree/master/docs
>>   - https://github.com/apache/tomee/tree/master/examples
>>
>> In the 'docs' directory alone there are 165 files that have
>> "Unrevised" as the header or no header at all.  We need to get a
>> header on all 165 of them.
>>
>>
>>
>> If you're looking for a way to contribute, there are 165 of them
>> right there.  At 15 minutes each document that's 2475 minutes or
>> 41.25 hours of community work.
>>
>>    ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^ ^   ^ 
>> ^  ^  ^  ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^  ^   ^  ^  ^ ^  ^  ^  ^ 
>> ^   ^  ^  ^  ^
>>
>> :)
>>
>> What we need is each doc to be reviewed, checked for any formatting
>> issues such as inconsistent h1, h2, h3 usage, then make your best
>> guess on what the topic is (JavaMail, JMS, CDI, JPA, etc), then set
>> that as the header `index-group=JMS` and submit a PR along with any
>> updates to the document you think are good (maybe none at all)
>>
>> Here's a couple sample commits:
>>
>>   -
>> https://github.com/apache/tomee/commit/bdee81d34c60644b755621254a535d0d8757eb21
>>   -
>> https://github.com/apache/tomee/commit/e2190a47c211c870680d761efd6d025d935546c7
>>
>>
>> If you'd like to build the docs locally, run this long command and
>> then open your browser to http://localhost:8080
>>
>>   - git clone [hidden email]:apache/tomee-site-generator.git && cd
>> tomee-site-generator && mvn clean compile -Djbake.http=true
>>
>>
>> On the formatting inconsistencies:
>>
>>   - We use to use Confluence.  There are actually some pages still
>> with that old format.
>>   - Some docs randomly start at h3 or h5.  They need to start at h1
>> and strictly not jump to h3 without an h2 in the middle.
>>   - If you have the energy to convert it from Markdown to Asciidoc, yay!
>>
>> We need to do this for both the docs and examples.
>>
>>   - https://github.com/apache/tomee/tree/master/docs
>>   - https://github.com/apache/tomee/tree/master/examples
>>
>>
>
Reply | Threaded
Open this post in threaded view
|

Re: Documentation Contribution Opportunities

Matthew Broadhead-2
yes that is what i mean.
also i was looking through the JBake docs and it is possible to define
tags on pages.  this might be useful where a page is relevant to more
than one index?

On 03/12/2018 16:25, Bruno Baptista wrote:

> Hi
>
> Do you mean, the Apache license in header on the top of each source file?
>
> Cheers
>
> Bruno Baptista
> https://twitter.com/brunobat_
>
>
> On 03/12/18 11:25, Matthew Broadhead wrote:
>> Should the licence be stored centrally and appended to the top (or
>> bottom) of each page?
>>
>> On 03/12/2018 04:21, David Blevins wrote:
>>> Hello hopeful contributors!
>>>
>>> As of this weekend we have two new index pages for our documentation
>>> on the website:
>>>
>>>   - http://tomee.apache.org/tomee-8.0/docs/
>>>   - http://tomee.apache.org/tomee-8.0/examples/
>>>
>>> The source for each of these index pages is generated by walking
>>> over each Markdown or Asciidoc file in these two sections of the
>>> main repo and looking for an `index-group=Foo` header in the
>>> document.  That's how they get grouped.
>>>
>>>   - https://github.com/apache/tomee/tree/master/docs
>>>   - https://github.com/apache/tomee/tree/master/examples
>>>
>>> In the 'docs' directory alone there are 165 files that have
>>> "Unrevised" as the header or no header at all.  We need to get a
>>> header on all 165 of them.
>>>
>>>
>>>
>>> If you're looking for a way to contribute, there are 165 of them
>>> right there.  At 15 minutes each document that's 2475 minutes or
>>> 41.25 hours of community work.
>>>
>>>    ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^ ^   ^ 
>>> ^  ^  ^  ^  ^  ^  ^   ^  ^  ^  ^  ^  ^  ^  ^   ^  ^  ^ ^  ^  ^  ^ 
>>> ^   ^  ^  ^  ^
>>>
>>> :)
>>>
>>> What we need is each doc to be reviewed, checked for any formatting
>>> issues such as inconsistent h1, h2, h3 usage, then make your best
>>> guess on what the topic is (JavaMail, JMS, CDI, JPA, etc), then set
>>> that as the header `index-group=JMS` and submit a PR along with any
>>> updates to the document you think are good (maybe none at all)
>>>
>>> Here's a couple sample commits:
>>>
>>>   -
>>> https://github.com/apache/tomee/commit/bdee81d34c60644b755621254a535d0d8757eb21
>>>   -
>>> https://github.com/apache/tomee/commit/e2190a47c211c870680d761efd6d025d935546c7
>>>
>>>
>>> If you'd like to build the docs locally, run this long command and
>>> then open your browser to http://localhost:8080
>>>
>>>   - git clone [hidden email]:apache/tomee-site-generator.git && cd
>>> tomee-site-generator && mvn clean compile -Djbake.http=true
>>>
>>>
>>> On the formatting inconsistencies:
>>>
>>>   - We use to use Confluence.  There are actually some pages still
>>> with that old format.
>>>   - Some docs randomly start at h3 or h5.  They need to start at h1
>>> and strictly not jump to h3 without an h2 in the middle.
>>>   - If you have the energy to convert it from Markdown to Asciidoc,
>>> yay!
>>>
>>> We need to do this for both the docs and examples.
>>>
>>>   - https://github.com/apache/tomee/tree/master/docs
>>>   - https://github.com/apache/tomee/tree/master/examples
>>>
>>>
>>

Reply | Threaded
Open this post in threaded view
|

Re: Documentation Contribution Opportunities

David Blevins-2
> On Dec 3, 2018, at 1:46 AM, Matthew Broadhead <[hidden email]> wrote:
>
> I would be happy to do this task.  But how to avoid conflicting PRs?

I think we need someone to volunteer to take the head and coordinate.  This could be grouping the docs up and filing a few JIRAs.

Maybe something like this:  https://lists.apache.org/thread.html/5a5b59289d2b4d045154aa29978f94e3362d894a65ca87c9b19a121e@1164234823@%3Cdev.tomee.apache.org%3E

> On Dec 3, 2018, at 7:48 AM, Matthew Broadhead <[hidden email]> wrote:
>
> also i was looking through the JBake docs and it is possible to define tags on pages.  this might be useful where a page is relevant to more than one index?

We could certainly do that.  I did the same digging and found the code JBake uses to get the tags and used it to generate the indexes we have:

 - https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/GroupedIndex.java#L165

You're absolutely correct that we could really have many different kinds of tags.  Heck, there could be a "suggested" tag that suggests other examples to try.  There could be a "related" tag that points at other key docs.

Another idea for either the tags or template or both is that we really should somehow link the examples zip on each examples page.

 - http://archive.apache.org/dist/tomee/tomee-8.0.0-M1/examples-8.0.0-M1-src.zip

It would also be cool to restore the Javadoc links, see the "APIs Used" section at the bottom:

 - http://tomee.apache.org/examples-trunk/simple-webservice/README.html

Effectively I was using Perl to "grep" the imports and look for javax uses then creating links to the javadoc.  Heck, now that Jakarta EE is open source, we could even be publishing that javadoc right on the TomEE site.  We could do that for MicroProfile as well which currently isn't being published anywhere and could drive value into our website.  We would publish the exact versions that are used by that version of TomEE.


>> On 03/12/18 11:25, Matthew Broadhead wrote:
>>> Should the licence be stored centrally and appended to the top (or bottom) of each page?

We'd have to do some experimenting to see how adding license headers would affect the JBake generation.


-David




Reply | Threaded
Open this post in threaded view
|

Re: Documentation Contribution Opportunities

David Blevins-2
Thank you Matthew, Daniel, Cesar and Sendil for the documentation PRs and Cesar and Otavio for the reviews.  They're all applied!

I really love seeing the CCS and template fixes!  It looks way more mobile-friendly.

I seem to be blocked out of svn at the moment, but as soon as this is resolved I should be able to publish the site.

It's really amazing how far it's come and how many contributors it has in just two weeks!


-David

Reply | Threaded
Open this post in threaded view
|

Re: Documentation Contribution Opportunities

Mitia Alexandrov
By the way, I've scrolled through the code. I see a lot of the code which
is not "JavaDoc"-umented. I can add all of the JavaDoc. But I would like to
make module by module. Is it ok for you? May be there are more preferable
modules that have to be documented?

Regards,
Dmitry

чт, 6 дек. 2018 г. в 05:01, David Blevins <[hidden email]>:

> Thank you Matthew, Daniel, Cesar and Sendil for the documentation PRs and
> Cesar and Otavio for the reviews.  They're all applied!
>
> I really love seeing the CCS and template fixes!  It looks way more
> mobile-friendly.
>
> I seem to be blocked out of svn at the moment, but as soon as this is
> resolved I should be able to publish the site.
>
> It's really amazing how far it's come and how many contributors it has in
> just two weeks!
>
>
> -David
>
>
Reply | Threaded
Open this post in threaded view
|

Re: Documentation Contribution Opportunities

David Blevins-2
I would vote for the TomEE Maven Plugin, which has a lot of features.  Any love it gets would help many people.

If you're up for pushing the bounds of creativity a bit, here's a fun idea.

 - write the javadoc in asciidoc format : https://asciidoctor.org/news/2013/06/03/asciidoclet-announcement/

If the majority of our javadoc was in asciidoc, we could potentially improve the site generator to not just pull README.md and README.adoc files as it currently does, but it could potentially pull chunks of asciidoc straight from the source code.

We don't need to leverage that now, but we certainly could in the future.  Even very near future (I'm really enjoying hacking on the website infrastructure).

I plan to dedicate this weekend to getting the javadoc online, which would give us this:

- http://tomee.apache.org/tomee-8.0/javadocs/
- http://tomee.apache.org/tomee-8.0/examples/ 
- http://tomee.apache.org/tomee-8.0/docs/


--
David Blevins
http://twitter.com/dblevins
http://www.tomitribe.com

> On Dec 6, 2018, at 12:21 AM, Mitia Alexandrov <[hidden email]> wrote:
>
> By the way, I've scrolled through the code. I see a lot of the code which
> is not "JavaDoc"-umented. I can add all of the JavaDoc. But I would like to
> make module by module. Is it ok for you? May be there are more preferable
> modules that have to be documented?
>
> Regards,
> Dmitry
>
> чт, 6 дек. 2018 г. в 05:01, David Blevins <[hidden email]>:
>
>> Thank you Matthew, Daniel, Cesar and Sendil for the documentation PRs and
>> Cesar and Otavio for the reviews.  They're all applied!
>>
>> I really love seeing the CCS and template fixes!  It looks way more
>> mobile-friendly.
>>
>> I seem to be blocked out of svn at the moment, but as soon as this is
>> resolved I should be able to publish the site.
>>
>> It's really amazing how far it's come and how many contributors it has in
>> just two weeks!
>>
>>
>> -David
>>
>>

Reply | Threaded
Open this post in threaded view
|

Re: Documentation Contribution Opportunities

Mitia Alexandrov
Wilco :)

чт, 6 дек. 2018 г. в 23:43, David Blevins <[hidden email]>:

> I would vote for the TomEE Maven Plugin, which has a lot of features.  Any
> love it gets would help many people.
>
> If you're up for pushing the bounds of creativity a bit, here's a fun idea.
>
>  - write the javadoc in asciidoc format :
> https://asciidoctor.org/news/2013/06/03/asciidoclet-announcement/
>
> If the majority of our javadoc was in asciidoc, we could potentially
> improve the site generator to not just pull README.md and README.adoc files
> as it currently does, but it could potentially pull chunks of asciidoc
> straight from the source code.
>
> We don't need to leverage that now, but we certainly could in the future.
> Even very near future (I'm really enjoying hacking on the website
> infrastructure).
>
> I plan to dedicate this weekend to getting the javadoc online, which would
> give us this:
>
> - http://tomee.apache.org/tomee-8.0/javadocs/
> - http://tomee.apache.org/tomee-8.0/examples/
> - http://tomee.apache.org/tomee-8.0/docs/
>
>
> --
> David Blevins
> http://twitter.com/dblevins
> http://www.tomitribe.com
>
> > On Dec 6, 2018, at 12:21 AM, Mitia Alexandrov <[hidden email]>
> wrote:
> >
> > By the way, I've scrolled through the code. I see a lot of the code which
> > is not "JavaDoc"-umented. I can add all of the JavaDoc. But I would like
> to
> > make module by module. Is it ok for you? May be there are more preferable
> > modules that have to be documented?
> >
> > Regards,
> > Dmitry
> >
> > чт, 6 дек. 2018 г. в 05:01, David Blevins <[hidden email]>:
> >
> >> Thank you Matthew, Daniel, Cesar and Sendil for the documentation PRs
> and
> >> Cesar and Otavio for the reviews.  They're all applied!
> >>
> >> I really love seeing the CCS and template fixes!  It looks way more
> >> mobile-friendly.
> >>
> >> I seem to be blocked out of svn at the moment, but as soon as this is
> >> resolved I should be able to publish the site.
> >>
> >> It's really amazing how far it's come and how many contributors it has
> in
> >> just two weeks!
> >>
> >>
> >> -David
> >>
> >>
>
>
Reply | Threaded
Open this post in threaded view
|

Re: Documentation Contribution Opportunities

David Blevins-2
In reply to this post by David Blevins-2
> On Dec 5, 2018, at 7:01 PM, David Blevins <[hidden email]> wrote:
>
> I seem to be blocked out of svn at the moment, but as soon as this is resolved I should be able to publish the site.

Site published!  It's really looking fantastic!

In an effort to be more organized, I created a parent JIRA task for improvements to the TomEE Site Generator:

 - https://issues.apache.org/jira/browse/TOMEE-2341

I've filled in some ideas people can hack on:

 - Publish Javadocs
 - Write Javadocs in Asciidoc
 - Generated Index for community/ docs
 - Add `` to all annotations outside codeblocks
 - Generate Javadoc '@see' references to our examples and docs

Each is a separate JIRA so more people can have fun.


-David


Reply | Threaded
Open this post in threaded view
|

Re: Documentation Contribution Opportunities

Daniel Dias Dos Santos
Hi David,

Please explain these two issues to me :

 - Publish Javadocs
 - Write Javadocs in Asciidoc

thanks .

--

*Daniel Dias dos Santos*
Java Developer
SouJava & JCP Member
GitHub: https://github.com/Daniel-Dos
Linkedin: www.linkedin.com/in/danieldiasjava
Twitter: http://twitter.com/danieldiasjava


Em dom, 9 de dez de 2018 às 02:32, David Blevins <[hidden email]>
escreveu:

> > On Dec 5, 2018, at 7:01 PM, David Blevins <[hidden email]>
> wrote:
> >
> > I seem to be blocked out of svn at the moment, but as soon as this is
> resolved I should be able to publish the site.
>
> Site published!  It's really looking fantastic!
>
> In an effort to be more organized, I created a parent JIRA task for
> improvements to the TomEE Site Generator:
>
>  - https://issues.apache.org/jira/browse/TOMEE-2341
>
> I've filled in some ideas people can hack on:
>
>  - Publish Javadocs
>  - Write Javadocs in Asciidoc
>  - Generated Index for community/ docs
>  - Add `` to all annotations outside codeblocks
>  - Generate Javadoc '@see' references to our examples and docs
>
> Each is a separate JIRA so more people can have fun.
>
>
> -David
>
>
>
Reply | Threaded
Open this post in threaded view
|

Re: Documentation Contribution Opportunities

David Blevins-2
> On Dec 8, 2018, at 9:06 PM, Daniel Dias Dos Santos <[hidden email]> wrote:
>
> Hi David,
>
> Please explain these two issues to me :
>
> - Publish Javadocs

The funny thing is I read too quickly and read "please assign these two issues to me", either way the outcome ended up being the same :)

I stubbed out the code and used Javadoc to describe the code in detail:

 - https://github.com/apache/tomee-site-generator/blob/a96d23581868abff30270115b113df7292872e8b/src/main/java/org/apache/tomee/website/Javadocs.java

I've actually always wanted to try that -- use javadoc as the requirements docs.  It's funny that the first time is on code that is supposed to generate Javadoc :)

Anyway, if you want to hack on it, let me know and I'll assign the task to you and spend my day on one of the other site generation tasks.

> - Write Javadocs in Asciidoc

I'll go grab a coffee and come back to detail this one.


-David

Reply | Threaded
Open this post in threaded view
|

Re: Documentation Contribution Opportunities

David Blevins-2
> On Dec 9, 2018, at 9:48 AM, David Blevins <[hidden email]> wrote:
>
>> - Write Javadocs in Asciidoc

I created a "Wish" JIRA for this one and detailed some steps:

 - https://issues.apache.org/jira/browse/TOMEE-2347

That would be for the main build.  Here's a separate JIRA for doing that in the Javadoc generator we need for the website:

 - https://issues.apache.org/jira/browse/TOMEE-2343


Some background on my goofy thinking.  Let me try and be as succinct as possible without losing everyone.  Here's the story of just one configuration property, `maxAge` on the Stateless container.

## MaxAge

Search this page for the phrase "this will happen gracefully" where `maxAge` is defined.

 - http://tomee.apache.org/tomee-8.0/docs/statelesscontainer-config.html

That page was generated from this file which has Markdown embedded in it:

 - https://github.com/apache/tomee/blob/master/container/openejb-core/src/main/resources/META-INF/org.apache.openejb/service-jar.xml#L150

Here's the actual piece of code that should probably have that Markdown (or asciidoc) as Javadoc:

 - https://github.com/apache/tomee/blob/master/container/openejb-core/src/main/java/org/apache/openejb/core/stateless/StatelessContainerFactory.java#L105

## Issues

Our effort to maintain the documentation for the MaxAge setting is a little high IMO because a few things:

 - the documentation for `maxAge` is not as close to the code as possible.  You need to know about the existence of the `service-jar.xml`.

 - the code that generated the file `docs/statelesscontainer-config.adoc` in our source is hard or impossible to find.  You need to know that file was generated from the service-jar.xml and know where the code is that did this work.  I wrote that code, but I don't remember where it is or if I even kept it.

If we changed the definition of `maxAge`, doing "the right thing" would involve updating:

 - html formatted javadoc on `StatelessContainerFactory#setMaxAge`
 - markdown formatted comments in service-jar.xml
 - asciidoc formatted description in `docs/statelesscontainer-config.adoc`

## The very tempting solution

Ideally, you just write Javadoc and "the right thing happens" even if you don't know how.

The very tempting solution is to take the asciidoc from `docs/statelesscontainer-config.adoc` and:

 - push it onto the `StatelessContainerFactory.java` file as javadoc
 - delete the `docs/statelesscontainer-config.adoc` file
 - delete the related comments from `service-jar.xml
 - write some code so JBake can generate `docs/statelesscontainer-config.html` using mostly the javadoc in `StatelessContainerFactory.java`

It's slightly crazing thinking, I know, but that's me :)


-David

Reply | Threaded
Open this post in threaded view
|

Re: Documentation Contribution Opportunities

Daniel Dias Dos Santos
HI David,

basically I would have to move the comments of:


https://github.com/apache/tomee/blob/master/container/openejb-core/src/main/resources/META-INF/org.apache.openejb/service-jar.xml#L150


and add the same ones here :

https://github.com/apache/tomee/blob/master/container/openejb-core/src/main/java/org/apache/openejb/core/stateless/StatelessContainerFactory.java#L105

, only in the format of asciidoc .

so for this for example, you would also have to convert to asciidoc:

https://github.com/apache/tomee/blob/master/container/openejb-jee/src/main/java/org/apache/openejb/jee/AbsoluteOrdering.java#L27L44



--

*Daniel Dias dos Santos*
Java Developer
SouJava & JCP Member
GitHub: https://github.com/Daniel-Dos
Linkedin: www.linkedin.com/in/danieldiasjava
Twitter: http://twitter.com/danieldiasjava


Em dom, 9 de dez de 2018 às 19:00, David Blevins <[hidden email]>
escreveu:

> > On Dec 9, 2018, at 9:48 AM, David Blevins <[hidden email]>
> wrote:
> >
> >> - Write Javadocs in Asciidoc
>
> I created a "Wish" JIRA for this one and detailed some steps:
>
>  - https://issues.apache.org/jira/browse/TOMEE-2347
>
> That would be for the main build.  Here's a separate JIRA for doing that
> in the Javadoc generator we need for the website:
>
>  - https://issues.apache.org/jira/browse/TOMEE-2343
>
>
> Some background on my goofy thinking.  Let me try and be as succinct as
> possible without losing everyone.  Here's the story of just one
> configuration property, `maxAge` on the Stateless container.
>
> ## MaxAge
>
> Search this page for the phrase "this will happen gracefully" where
> `maxAge` is defined.
>
>  - http://tomee.apache.org/tomee-8.0/docs/statelesscontainer-config.html
>
> That page was generated from this file which has Markdown embedded in it:
>
>  -
> https://github.com/apache/tomee/blob/master/container/openejb-core/src/main/resources/META-INF/org.apache.openejb/service-jar.xml#L150
>
> Here's the actual piece of code that should probably have that Markdown
> (or asciidoc) as Javadoc:
>
>  -
> https://github.com/apache/tomee/blob/master/container/openejb-core/src/main/java/org/apache/openejb/core/stateless/StatelessContainerFactory.java#L105
>
> ## Issues
>
> Our effort to maintain the documentation for the MaxAge setting is a
> little high IMO because a few things:
>
>  - the documentation for `maxAge` is not as close to the code as
> possible.  You need to know about the existence of the `service-jar.xml`.
>
>  - the code that generated the file `docs/statelesscontainer-config.adoc`
> in our source is hard or impossible to find.  You need to know that file
> was generated from the service-jar.xml and know where the code is that did
> this work.  I wrote that code, but I don't remember where it is or if I
> even kept it.
>
> If we changed the definition of `maxAge`, doing "the right thing" would
> involve updating:
>
>  - html formatted javadoc on `StatelessContainerFactory#setMaxAge`
>  - markdown formatted comments in service-jar.xml
>  - asciidoc formatted description in `docs/statelesscontainer-config.adoc`
>
> ## The very tempting solution
>
> Ideally, you just write Javadoc and "the right thing happens" even if you
> don't know how.
>
> The very tempting solution is to take the asciidoc from
> `docs/statelesscontainer-config.adoc` and:
>
>  - push it onto the `StatelessContainerFactory.java` file as javadoc
>  - delete the `docs/statelesscontainer-config.adoc` file
>  - delete the related comments from `service-jar.xml
>  - write some code so JBake can generate
> `docs/statelesscontainer-config.html` using mostly the javadoc in
> `StatelessContainerFactory.java`
>
> It's slightly crazing thinking, I know, but that's me :)
>
>
> -David
>
>
Reply | Threaded
Open this post in threaded view
|

Re: Documentation Contribution Opportunities

David Blevins-2
> On Dec 9, 2018, at 2:10 PM, Daniel Dias Dos Santos <[hidden email]> wrote:
>
> basically I would have to move the comments of:
>
>  - https://github.com/apache/tomee/blob/master/container/openejb-core/src/main/resources/META-INF/org.apache.openejb/service-jar.xml#L150
>
> and add the same ones here :
>
>  - https://github.com/apache/tomee/blob/master/container/openejb-core/src/main/java/org/apache/openejb/core/stateless/StatelessContainerFactory.java#L105
>
> , only in the format of asciidoc .

That's one idea of the benefits of using Asciidoc in our Javadoc.  The service-jar.xml specifically has been in the project for a long time, so it'd be great to hear more thoughts.

However the general idea, which is bigger than service-jar.xml, is that the more we're pushing good documentation into the source code, the more opportunities we have to use it to feed docs on the website.  Since the website documentation is primarily Asciidoc, lining that up with our Javadoc could be very smart.

We don't necessarily have to switch the comments in the service-jar.xml over as a first step.  The first step could be to simply start writing Javadoc for classes that don't have them.

> so for this for example, you would also have to convert to asciidoc:
>
> https://github.com/apache/tomee/blob/master/container/openejb-jee/src/main/java/org/apache/openejb/jee/AbsoluteOrdering.java#L27L44

In my opinion, the JAXB-generated Javadoc is of low to no value and could just be deleted.


-David

Reply | Threaded
Open this post in threaded view
|

Re: Documentation Contribution Opportunities

Daniel Dias Dos Santos
now I'm lost in what I have to do David.  :  )
--

*Daniel Dias dos Santos*
Java Developer
SouJava & JCP Member
GitHub: https://github.com/Daniel-Dos
Linkedin: www.linkedin.com/in/danieldiasjava
Twitter: http://twitter.com/danieldiasjava


Em dom, 9 de dez de 2018 às 20:28, David Blevins <[hidden email]>
escreveu:

> > On Dec 9, 2018, at 2:10 PM, Daniel Dias Dos Santos <
> [hidden email]> wrote:
> >
> > basically I would have to move the comments of:
> >
> >  -
> https://github.com/apache/tomee/blob/master/container/openejb-core/src/main/resources/META-INF/org.apache.openejb/service-jar.xml#L150
> >
> > and add the same ones here :
> >
> >  -
> https://github.com/apache/tomee/blob/master/container/openejb-core/src/main/java/org/apache/openejb/core/stateless/StatelessContainerFactory.java#L105
> >
> > , only in the format of asciidoc .
>
> That's one idea of the benefits of using Asciidoc in our Javadoc.  The
> service-jar.xml specifically has been in the project for a long time, so
> it'd be great to hear more thoughts.
>
> However the general idea, which is bigger than service-jar.xml, is that
> the more we're pushing good documentation into the source code, the more
> opportunities we have to use it to feed docs on the website.  Since the
> website documentation is primarily Asciidoc, lining that up with our
> Javadoc could be very smart.
>
> We don't necessarily have to switch the comments in the service-jar.xml
> over as a first step.  The first step could be to simply start writing
> Javadoc for classes that don't have them.
>
> > so for this for example, you would also have to convert to asciidoc:
> >
> >
> https://github.com/apache/tomee/blob/master/container/openejb-jee/src/main/java/org/apache/openejb/jee/AbsoluteOrdering.java#L27L44
>
> In my opinion, the JAXB-generated Javadoc is of low to no value and could
> just be deleted.
>
>
> -David
>
>
Reply | Threaded
Open this post in threaded view
|

Re: Documentation Contribution Opportunities

David Blevins-2
The simplest task is to complete the Javadocs class I stubbed out:

 - https://github.com/apache/tomee-site-generator/blob/a96d23581868abff30270115b113df7292872e8b/src/main/java/org/apache/tomee/website/Javadocs.java
   https://issues.apache.org/jira/browse/TOMEE-2342 Publish Javadocs

Give it a read and see if you have any questions.

Bottom line goal of that one is one huge chunk of javadoc made from all src/main/java/ contents combined.


--
David Blevins
http://twitter.com/dblevins
http://www.tomitribe.com

> On Dec 9, 2018, at 2:35 PM, Daniel Dias Dos Santos <[hidden email]> wrote:
>
> now I'm lost in what I have to do David.  :  )
> --
>
> *Daniel Dias dos Santos*
> Java Developer
> SouJava & JCP Member
> GitHub: https://github.com/Daniel-Dos
> Linkedin: www.linkedin.com/in/danieldiasjava
> Twitter: http://twitter.com/danieldiasjava
>
>
> Em dom, 9 de dez de 2018 às 20:28, David Blevins <[hidden email]>
> escreveu:
>
>>> On Dec 9, 2018, at 2:10 PM, Daniel Dias Dos Santos <
>> [hidden email]> wrote:
>>>
>>> basically I would have to move the comments of:
>>>
>>> -
>> https://github.com/apache/tomee/blob/master/container/openejb-core/src/main/resources/META-INF/org.apache.openejb/service-jar.xml#L150
>>>
>>> and add the same ones here :
>>>
>>> -
>> https://github.com/apache/tomee/blob/master/container/openejb-core/src/main/java/org/apache/openejb/core/stateless/StatelessContainerFactory.java#L105
>>>
>>> , only in the format of asciidoc .
>>
>> That's one idea of the benefits of using Asciidoc in our Javadoc.  The
>> service-jar.xml specifically has been in the project for a long time, so
>> it'd be great to hear more thoughts.
>>
>> However the general idea, which is bigger than service-jar.xml, is that
>> the more we're pushing good documentation into the source code, the more
>> opportunities we have to use it to feed docs on the website.  Since the
>> website documentation is primarily Asciidoc, lining that up with our
>> Javadoc could be very smart.
>>
>> We don't necessarily have to switch the comments in the service-jar.xml
>> over as a first step.  The first step could be to simply start writing
>> Javadoc for classes that don't have them.
>>
>>> so for this for example, you would also have to convert to asciidoc:
>>>
>>>
>> https://github.com/apache/tomee/blob/master/container/openejb-jee/src/main/java/org/apache/openejb/jee/AbsoluteOrdering.java#L27L44
>>
>> In my opinion, the JAXB-generated Javadoc is of low to no value and could
>> just be deleted.
>>
>>
>> -David
>>
>>

Reply | Threaded
Open this post in threaded view
|

Re: Documentation Contribution Opportunities

Daniel Dias Dos Santos
cool .

then the code for JavaDocs.java would look like this:

https://github.com/apache/tomee-site-generator/blob/a96d23581868abff30270115b113df7292872e8b/src/main/java/org/apache/tomee/website/Examples.java

assign this task to me, which I try to do  : )

thanks .
--

*Daniel Dias dos Santos*
Java Developer
SouJava & JCP Member
GitHub: https://github.com/Daniel-Dos
Linkedin: www.linkedin.com/in/danieldiasjava
Twitter: http://twitter.com/danieldiasjava


Em dom, 9 de dez de 2018 às 21:17, David Blevins <[hidden email]>
escreveu:

> The simplest task is to complete the Javadocs class I stubbed out:
>
>  -
> https://github.com/apache/tomee-site-generator/blob/a96d23581868abff30270115b113df7292872e8b/src/main/java/org/apache/tomee/website/Javadocs.java
>    https://issues.apache.org/jira/browse/TOMEE-2342 Publish Javadocs
>
> Give it a read and see if you have any questions.
>
> Bottom line goal of that one is one huge chunk of javadoc made from all
> src/main/java/ contents combined.
>
>
> --
> David Blevins
> http://twitter.com/dblevins
> http://www.tomitribe.com
>
> > On Dec 9, 2018, at 2:35 PM, Daniel Dias Dos Santos <
> [hidden email]> wrote:
> >
> > now I'm lost in what I have to do David.  :  )
> > --
> >
> > *Daniel Dias dos Santos*
> > Java Developer
> > SouJava & JCP Member
> > GitHub: https://github.com/Daniel-Dos
> > Linkedin: www.linkedin.com/in/danieldiasjava
> > Twitter: http://twitter.com/danieldiasjava
> >
> >
> > Em dom, 9 de dez de 2018 às 20:28, David Blevins <
> [hidden email]>
> > escreveu:
> >
> >>> On Dec 9, 2018, at 2:10 PM, Daniel Dias Dos Santos <
> >> [hidden email]> wrote:
> >>>
> >>> basically I would have to move the comments of:
> >>>
> >>> -
> >>
> https://github.com/apache/tomee/blob/master/container/openejb-core/src/main/resources/META-INF/org.apache.openejb/service-jar.xml#L150
> >>>
> >>> and add the same ones here :
> >>>
> >>> -
> >>
> https://github.com/apache/tomee/blob/master/container/openejb-core/src/main/java/org/apache/openejb/core/stateless/StatelessContainerFactory.java#L105
> >>>
> >>> , only in the format of asciidoc .
> >>
> >> That's one idea of the benefits of using Asciidoc in our Javadoc.  The
> >> service-jar.xml specifically has been in the project for a long time, so
> >> it'd be great to hear more thoughts.
> >>
> >> However the general idea, which is bigger than service-jar.xml, is that
> >> the more we're pushing good documentation into the source code, the more
> >> opportunities we have to use it to feed docs on the website.  Since the
> >> website documentation is primarily Asciidoc, lining that up with our
> >> Javadoc could be very smart.
> >>
> >> We don't necessarily have to switch the comments in the service-jar.xml
> >> over as a first step.  The first step could be to simply start writing
> >> Javadoc for classes that don't have them.
> >>
> >>> so for this for example, you would also have to convert to asciidoc:
> >>>
> >>>
> >>
> https://github.com/apache/tomee/blob/master/container/openejb-jee/src/main/java/org/apache/openejb/jee/AbsoluteOrdering.java#L27L44
> >>
> >> In my opinion, the JAXB-generated Javadoc is of low to no value and
> could
> >> just be deleted.
> >>
> >>
> >> -David
> >>
> >>
>
>
Reply | Threaded
Open this post in threaded view
|

Re: Documentation Contribution Opportunities

David Blevins-2
> On Dec 9, 2018, at 3:57 PM, Daniel Dias Dos Santos <[hidden email]> wrote:
>
> cool .
>
> then the code for JavaDocs.java would look like this:
>
> https://github.com/apache/tomee-site-generator/blob/a96d23581868abff30270115b113df7292872e8b/src/main/java/org/apache/tomee/website/Examples.java
>
> assign this task to me, which I try to do  : )

You got it.  The JIRA is all yours!  See also this example of doing a recursive walk looking for files with a particular name:

 - https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Docs.java#L51



-David


12