Re: [jakartaee-platform-dev] [incubation] Hosting project documentation

[Wayne Beaton <wayne.beaton@xxxxxxxxxxxxxxxxxxxxxx>]

TL:DR: Yes.

One way to think about it is this... if the project license allows for others to take the content and host it on a service like readthedocs, then project committers can too.

readthedocs is an external resource and so, if it's used an official means of distributing project content, then the project team needs to make sure that the keys are shared by more than one committer (there's more in the handbook), and care must be taken to leverage that external resource in an open, transparent, and vendor neutral manner. 

I know that this isn't the question that you asked, but... As I said on the incubation list, documentation is a core project resource and so the source should be managed along with the code (ideally in a EF-managed Git repository). Documentation is a resource that adopters, contributors, and the community in general needs to have access to under the same set of rules as the project code. Whether or not a tutorial qualifies as documentation is something that the project team needs to determine (with help, if needed, from the PMC).

HTH,

Wayne

On Sat, Feb 1, 2020 at 9:50 AM Werner Keil <werner.keil@xxxxxxx> wrote:

Hi Wayne,

 

Thanks for the update on using readthedocs.io.

 

Would that also be an Option for other documentation like the Jakarta EE Tutorial?

 

Werner

 

Sent from Mail for Windows 10

 

From: Wayne Beaton
Sent: Friday, January 31, 2020 21:48
To: Discussions for new Eclipse projects
Subject: Re: [incubation] Hosting project documentation on readthedocs.io

 

Hi Patrick.

 

Using readthedocs.io to deploy your documentation is fine. This would be considered an external resource; there's some more about them in the handbook. No formal permission is required, but there are some branding and level playing field requirements.

 

I'm pretty sure that you're doing this already, but will take the opportunity to reinforce that the sources for the documentation are project content (i.e., they must be stored in a Git repo that is managed by the Eclipse Foundation on behalf of the project). 

 

Regarding the copyright headers, there are two options outlined in the handbook (and repeated by the documentation generator).

• Copyright (c) {year} {owner}[ and others]; or
• Copyright (c) {date} Contributors to the Eclipse Foundation

 

HTH,

Wayne

 

 

On Fri, Jan 31, 2020 at 11:02 AM Patrick Masselink <patrick.masselink@xxxxxxxxxxxxxx> wrote:

Hi all,

I'm working on readthedocs support for hosting Eclipse CycloneDDS documentation. I've found other Eclipse projects already using readthedocs (i.e. IoT-Testware) but still I'd like to ask if there are any potential concerns.

Note the 3rd party tooling involved (Sphinx, doxygen, texlive etc.) is already required today, to build CycloneDDS documentation. My contribution will mostly involve configuration for automated readthedocs builds. Once the mechanism is in place i will apply for automatic RTD builds on pull-requests, to encourage contributors to add and improve documentation and to verify PRs don't break the docs build.

I intend to use a copyright notice similar to IoT-Testware (i.e. Copyright 2020, Eclipse CycloneDDS Contributors) and will also include the license.

Can I go ahead and once finished just do a pull-request? Or do we need any formal permission or i.e. a review of the artifacts we intend to publish?

Thanks,

Patrick Masselink

_______________________________________________
incubation mailing list
incubation@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/incubation

 

--

Wayne Beaton

Director of Open Source Projects | Eclipse Foundation, Inc.

 

--

Wayne Beaton

Director of Open Source Projects | Eclipse Foundation, Inc.