Potentially having some part of documentation in the main repo

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Potentially having some part of documentation in the main repo

David Blevins-2
Just wrote a long description on the definition of InvocationTime and MonitoredMethods in the JMX `@Monitor` functionality and I'm reminded on how much of a pain it is to contribute to the documentation.  It would be so much easier if some part of it was in the build.

I'm wondering if we want some sort of docs/ directory in our main repo.  Not thinking we add jbake to the main build, just the asciidoc.  The fancy processing can still happen elsewhere.

Docs like "how to contribute to the website" would stay where they are, but things like "configuring datasources" would definitely come in.  We'd then follow the Tomcat approach of:

 - https://tomcat.apache.org/tomcat-8.5-doc/index.html <https://tomcat.apache.org/tomcat-8.5-doc/index.html>
 - https://tomcat.apache.org/tomcat-8.0-doc/index.html <https://tomcat.apache.org/tomcat-8.0-doc/index.html>

etc.

I don't think we'd need to get too fancy and do one doc base per Web Profile, Plume, etc.  just this would be enough:

 - https://tomee.apache.org/tomee-8.0-doc/index.html <https://tomee.apache.org/tomee-8.0-doc/index.html>
 - https://tomee.apache.org/tomee-7.0-doc/index.html <https://tomee.apache.org/tomee-7.0-doc/index.html>
 - https://tomee.apache.org/tomee-1.7-doc/index.html <https://tomee.apache.org/tomee-1.7-doc/index.html>

When sheldon/chatterbox come in, they'd go:

 - https://tomee.apache.org/sheldon-3.0-doc/index.html <https://tomee.apache.org/sheldon-3.0-doc/index.html>
 - https://tomee.apache.org/chatterbox-2.1-doc/index.html <https://tomee.apache.org/chatterbox-2.1-doc/index.html>

I totally made up those version numbers for illustrative purposes.  You get the idea.

Related note, we actually have some documentation generated from the build and not regenerated.  This page for example was entirely generated from the default service-jar.xml:

 - http://tomee.apache.org/containers-and-resources.html <http://tomee.apache.org/containers-and-resources.html>

I remember doing that ages ago, like 2008-2011 range.  Aside from being likely out of date, it definitely highlights the awkward relationship between the docs and the source we currently have.


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

Reply | Threaded
Open this post in threaded view
|

Re: Potentially having some part of documentation in the main repo

Romain Manni-Bucau
+0 to have it all and sync somehow in the site build process - i like
having it with the code since it enables some more stuff to happen but it
increases contribution cost
-0 to have it partially to ensure we dont loose contributors

Side note: if you import it, ensure to update all the contributor docs and
github proxies please

Side note 2: we can still generate doc in another project depending on main
artifacts ;)

Le 17 sept. 2017 05:26, "David Blevins" <[hidden email]> a écrit :

> Just wrote a long description on the definition of InvocationTime and
> MonitoredMethods in the JMX `@Monitor` functionality and I'm reminded on
> how much of a pain it is to contribute to the documentation.  It would be
> so much easier if some part of it was in the build.
>
> I'm wondering if we want some sort of docs/ directory in our main repo.
> Not thinking we add jbake to the main build, just the asciidoc.  The fancy
> processing can still happen elsewhere.
>
> Docs like "how to contribute to the website" would stay where they are,
> but things like "configuring datasources" would definitely come in.  We'd
> then follow the Tomcat approach of:
>
>  - https://tomcat.apache.org/tomcat-8.5-doc/index.html <
> https://tomcat.apache.org/tomcat-8.5-doc/index.html>
>  - https://tomcat.apache.org/tomcat-8.0-doc/index.html <
> https://tomcat.apache.org/tomcat-8.0-doc/index.html>
>
> etc.
>
> I don't think we'd need to get too fancy and do one doc base per Web
> Profile, Plume, etc.  just this would be enough:
>
>  - https://tomee.apache.org/tomee-8.0-doc/index.html <
> https://tomee.apache.org/tomee-8.0-doc/index.html>
>  - https://tomee.apache.org/tomee-7.0-doc/index.html <
> https://tomee.apache.org/tomee-7.0-doc/index.html>
>  - https://tomee.apache.org/tomee-1.7-doc/index.html <
> https://tomee.apache.org/tomee-1.7-doc/index.html>
>
> When sheldon/chatterbox come in, they'd go:
>
>  - https://tomee.apache.org/sheldon-3.0-doc/index.html <
> https://tomee.apache.org/sheldon-3.0-doc/index.html>
>  - https://tomee.apache.org/chatterbox-2.1-doc/index.html <
> https://tomee.apache.org/chatterbox-2.1-doc/index.html>
>
> I totally made up those version numbers for illustrative purposes.  You
> get the idea.
>
> Related note, we actually have some documentation generated from the build
> and not regenerated.  This page for example was entirely generated from the
> default service-jar.xml:
>
>  - http://tomee.apache.org/containers-and-resources.html <
> http://tomee.apache.org/containers-and-resources.html>
>
> I remember doing that ages ago, like 2008-2011 range.  Aside from being
> likely out of date, it definitely highlights the awkward relationship
> between the docs and the source we currently have.
>
>
> --
> David Blevins
> http://twitter.com/dblevins
> http://www.tomitribe.com
>
>
Reply | Threaded
Open this post in threaded view
|

Re: Potentially having some part of documentation in the main repo

Jean-Louis MONTEIRO
I totally agree that our documentation is a pain and does not help us first
to right it and contributors to help.
Each time I have to do a fix or add something it's a pain.

So +1 to simplify it.
JBake, plain asciidoc, whatever. Just something simple.

--
Jean-Louis Monteiro
http://twitter.com/jlouismonteiro
http://www.tomitribe.com

On Sun, Sep 17, 2017 at 8:09 AM, Romain Manni-Bucau <[hidden email]>
wrote:

> +0 to have it all and sync somehow in the site build process - i like
> having it with the code since it enables some more stuff to happen but it
> increases contribution cost
> -0 to have it partially to ensure we dont loose contributors
>
> Side note: if you import it, ensure to update all the contributor docs and
> github proxies please
>
> Side note 2: we can still generate doc in another project depending on main
> artifacts ;)
>
> Le 17 sept. 2017 05:26, "David Blevins" <[hidden email]> a écrit
> :
>
> > Just wrote a long description on the definition of InvocationTime and
> > MonitoredMethods in the JMX `@Monitor` functionality and I'm reminded on
> > how much of a pain it is to contribute to the documentation.  It would be
> > so much easier if some part of it was in the build.
> >
> > I'm wondering if we want some sort of docs/ directory in our main repo.
> > Not thinking we add jbake to the main build, just the asciidoc.  The
> fancy
> > processing can still happen elsewhere.
> >
> > Docs like "how to contribute to the website" would stay where they are,
> > but things like "configuring datasources" would definitely come in.  We'd
> > then follow the Tomcat approach of:
> >
> >  - https://tomcat.apache.org/tomcat-8.5-doc/index.html <
> > https://tomcat.apache.org/tomcat-8.5-doc/index.html>
> >  - https://tomcat.apache.org/tomcat-8.0-doc/index.html <
> > https://tomcat.apache.org/tomcat-8.0-doc/index.html>
> >
> > etc.
> >
> > I don't think we'd need to get too fancy and do one doc base per Web
> > Profile, Plume, etc.  just this would be enough:
> >
> >  - https://tomee.apache.org/tomee-8.0-doc/index.html <
> > https://tomee.apache.org/tomee-8.0-doc/index.html>
> >  - https://tomee.apache.org/tomee-7.0-doc/index.html <
> > https://tomee.apache.org/tomee-7.0-doc/index.html>
> >  - https://tomee.apache.org/tomee-1.7-doc/index.html <
> > https://tomee.apache.org/tomee-1.7-doc/index.html>
> >
> > When sheldon/chatterbox come in, they'd go:
> >
> >  - https://tomee.apache.org/sheldon-3.0-doc/index.html <
> > https://tomee.apache.org/sheldon-3.0-doc/index.html>
> >  - https://tomee.apache.org/chatterbox-2.1-doc/index.html <
> > https://tomee.apache.org/chatterbox-2.1-doc/index.html>
> >
> > I totally made up those version numbers for illustrative purposes.  You
> > get the idea.
> >
> > Related note, we actually have some documentation generated from the
> build
> > and not regenerated.  This page for example was entirely generated from
> the
> > default service-jar.xml:
> >
> >  - http://tomee.apache.org/containers-and-resources.html <
> > http://tomee.apache.org/containers-and-resources.html>
> >
> > I remember doing that ages ago, like 2008-2011 range.  Aside from being
> > likely out of date, it definitely highlights the awkward relationship
> > between the docs and the source we currently have.
> >
> >
> > --
> > David Blevins
> > http://twitter.com/dblevins
> > http://www.tomitribe.com
> >
> >
>
   --
    Jean-Louis Monteiro
    http://twitter.com/jlouismonteiro
    http://www.tomitribe.com
Reply | Threaded
Open this post in threaded view
|

Re: Potentially having some part of documentation in the main repo

AndyG
+1 for asciidoc

Andy Gumbrecht.


On 19/09/17 10:15, Jean-Louis Monteiro wrote:

> I totally agree that our documentation is a pain and does not help us first
> to right it and contributors to help.
> Each time I have to do a fix or add something it's a pain.
>
> So +1 to simplify it.
> JBake, plain asciidoc, whatever. Just something simple.
>
> --
> Jean-Louis Monteiro
> http://twitter.com/jlouismonteiro
> http://www.tomitribe.com
>
> On Sun, Sep 17, 2017 at 8:09 AM, Romain Manni-Bucau <[hidden email]>
> wrote:
>
>> +0 to have it all and sync somehow in the site build process - i like
>> having it with the code since it enables some more stuff to happen but it
>> increases contribution cost
>> -0 to have it partially to ensure we dont loose contributors
>>
>> Side note: if you import it, ensure to update all the contributor docs and
>> github proxies please
>>
>> Side note 2: we can still generate doc in another project depending on main
>> artifacts ;)
>>
>> Le 17 sept. 2017 05:26, "David Blevins" <[hidden email]> a écrit
>> :
>>
>>> Just wrote a long description on the definition of InvocationTime and
>>> MonitoredMethods in the JMX `@Monitor` functionality and I'm reminded on
>>> how much of a pain it is to contribute to the documentation.  It would be
>>> so much easier if some part of it was in the build.
>>>
>>> I'm wondering if we want some sort of docs/ directory in our main repo.
>>> Not thinking we add jbake to the main build, just the asciidoc.  The
>> fancy
>>> processing can still happen elsewhere.
>>>
>>> Docs like "how to contribute to the website" would stay where they are,
>>> but things like "configuring datasources" would definitely come in.  We'd
>>> then follow the Tomcat approach of:
>>>
>>>   - https://tomcat.apache.org/tomcat-8.5-doc/index.html <
>>> https://tomcat.apache.org/tomcat-8.5-doc/index.html>
>>>   - https://tomcat.apache.org/tomcat-8.0-doc/index.html <
>>> https://tomcat.apache.org/tomcat-8.0-doc/index.html>
>>>
>>> etc.
>>>
>>> I don't think we'd need to get too fancy and do one doc base per Web
>>> Profile, Plume, etc.  just this would be enough:
>>>
>>>   - https://tomee.apache.org/tomee-8.0-doc/index.html <
>>> https://tomee.apache.org/tomee-8.0-doc/index.html>
>>>   - https://tomee.apache.org/tomee-7.0-doc/index.html <
>>> https://tomee.apache.org/tomee-7.0-doc/index.html>
>>>   - https://tomee.apache.org/tomee-1.7-doc/index.html <
>>> https://tomee.apache.org/tomee-1.7-doc/index.html>
>>>
>>> When sheldon/chatterbox come in, they'd go:
>>>
>>>   - https://tomee.apache.org/sheldon-3.0-doc/index.html <
>>> https://tomee.apache.org/sheldon-3.0-doc/index.html>
>>>   - https://tomee.apache.org/chatterbox-2.1-doc/index.html <
>>> https://tomee.apache.org/chatterbox-2.1-doc/index.html>
>>>
>>> I totally made up those version numbers for illustrative purposes.  You
>>> get the idea.
>>>
>>> Related note, we actually have some documentation generated from the
>> build
>>> and not regenerated.  This page for example was entirely generated from
>> the
>>> default service-jar.xml:
>>>
>>>   - http://tomee.apache.org/containers-and-resources.html <
>>> http://tomee.apache.org/containers-and-resources.html>
>>>
>>> I remember doing that ages ago, like 2008-2011 range.  Aside from being
>>> likely out of date, it definitely highlights the awkward relationship
>>> between the docs and the source we currently have.
>>>
>>>
>>> --
>>> David Blevins
>>> http://twitter.com/dblevins
>>> http://www.tomitribe.com
>>>
>>>

Reply | Threaded
Open this post in threaded view
|

Re: Potentially having some part of documentation in the main repo

Romain Manni-Bucau
arent we already using asciidoc? (
https://github.com/apache/tomee-site-generator/tree/master/src/main/jbake/content
)


Romain Manni-Bucau
@rmannibucau <https://twitter.com/rmannibucau> |  Blog
<https://blog-rmannibucau.rhcloud.com> | Old Blog
<http://rmannibucau.wordpress.com> | Github <https://github.com/rmannibucau> |
LinkedIn <https://www.linkedin.com/in/rmannibucau> | JavaEE Factory
<https://javaeefactory-rmannibucau.rhcloud.com>

2017-09-25 16:56 GMT+02:00 Andy Gumbrecht <[hidden email]>:

> +1 for asciidoc
>
> Andy Gumbrecht.
>
>
>
> On 19/09/17 10:15, Jean-Louis Monteiro wrote:
>
>> I totally agree that our documentation is a pain and does not help us
>> first
>> to right it and contributors to help.
>> Each time I have to do a fix or add something it's a pain.
>>
>> So +1 to simplify it.
>> JBake, plain asciidoc, whatever. Just something simple.
>>
>> --
>> Jean-Louis Monteiro
>> http://twitter.com/jlouismonteiro
>> http://www.tomitribe.com
>>
>> On Sun, Sep 17, 2017 at 8:09 AM, Romain Manni-Bucau <
>> [hidden email]>
>> wrote:
>>
>> +0 to have it all and sync somehow in the site build process - i like
>>> having it with the code since it enables some more stuff to happen but it
>>> increases contribution cost
>>> -0 to have it partially to ensure we dont loose contributors
>>>
>>> Side note: if you import it, ensure to update all the contributor docs
>>> and
>>> github proxies please
>>>
>>> Side note 2: we can still generate doc in another project depending on
>>> main
>>> artifacts ;)
>>>
>>> Le 17 sept. 2017 05:26, "David Blevins" <[hidden email]> a
>>> écrit
>>> :
>>>
>>> Just wrote a long description on the definition of InvocationTime and
>>>> MonitoredMethods in the JMX `@Monitor` functionality and I'm reminded on
>>>> how much of a pain it is to contribute to the documentation.  It would
>>>> be
>>>> so much easier if some part of it was in the build.
>>>>
>>>> I'm wondering if we want some sort of docs/ directory in our main repo.
>>>> Not thinking we add jbake to the main build, just the asciidoc.  The
>>>>
>>> fancy
>>>
>>>> processing can still happen elsewhere.
>>>>
>>>> Docs like "how to contribute to the website" would stay where they are,
>>>> but things like "configuring datasources" would definitely come in.
>>>> We'd
>>>> then follow the Tomcat approach of:
>>>>
>>>>   - https://tomcat.apache.org/tomcat-8.5-doc/index.html <
>>>> https://tomcat.apache.org/tomcat-8.5-doc/index.html>
>>>>   - https://tomcat.apache.org/tomcat-8.0-doc/index.html <
>>>> https://tomcat.apache.org/tomcat-8.0-doc/index.html>
>>>>
>>>> etc.
>>>>
>>>> I don't think we'd need to get too fancy and do one doc base per Web
>>>> Profile, Plume, etc.  just this would be enough:
>>>>
>>>>   - https://tomee.apache.org/tomee-8.0-doc/index.html <
>>>> https://tomee.apache.org/tomee-8.0-doc/index.html>
>>>>   - https://tomee.apache.org/tomee-7.0-doc/index.html <
>>>> https://tomee.apache.org/tomee-7.0-doc/index.html>
>>>>   - https://tomee.apache.org/tomee-1.7-doc/index.html <
>>>> https://tomee.apache.org/tomee-1.7-doc/index.html>
>>>>
>>>> When sheldon/chatterbox come in, they'd go:
>>>>
>>>>   - https://tomee.apache.org/sheldon-3.0-doc/index.html <
>>>> https://tomee.apache.org/sheldon-3.0-doc/index.html>
>>>>   - https://tomee.apache.org/chatterbox-2.1-doc/index.html <
>>>> https://tomee.apache.org/chatterbox-2.1-doc/index.html>
>>>>
>>>> I totally made up those version numbers for illustrative purposes.  You
>>>> get the idea.
>>>>
>>>> Related note, we actually have some documentation generated from the
>>>>
>>> build
>>>
>>>> and not regenerated.  This page for example was entirely generated from
>>>>
>>> the
>>>
>>>> default service-jar.xml:
>>>>
>>>>   - http://tomee.apache.org/containers-and-resources.html <
>>>> http://tomee.apache.org/containers-and-resources.html>
>>>>
>>>> I remember doing that ages ago, like 2008-2011 range.  Aside from being
>>>> likely out of date, it definitely highlights the awkward relationship
>>>> between the docs and the source we currently have.
>>>>
>>>>
>>>> --
>>>> David Blevins
>>>> http://twitter.com/dblevins
>>>> http://www.tomitribe.com
>>>>
>>>>
>>>>
>