Re: Contributing documentation from other sources

[Jesse Glick]

https://plugins.jenkins.io/github-branch-source/ and
https://plugins.jenkins.io/cloudbees-folder/ both still have
documentation hosted on cloudbees.com.

-- 
You received this message because you are subscribed to the Google Groups 
"Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to jenkinsci-dev+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/jenkinsci-dev/CANfRfr3%3DO13yfQF7jUTJXB08kWvOQsw8LgTKCGA7_eQW4%3DWCrA%40mail.gmail.com.

Re: Contributing documentation from other sources

[Mark Waite]

One example of content that might help (but would need modifications to fit 
into the jenkins.io structure) is the Jenkins command line interface 
documentation 
at 
https://docs.cloudbees.com/docs/admin-resources/latest/cli-guide/cli-guide-intro
 
.

A technical writer would need to evaluate that content in the Jenkins 
context to decide which parts are helpful and which parts are not relevant 
to a Jenkins user.

Mark Waite

On Wednesday, June 24, 2020 at 2:02:21 AM UTC-6 timja...@gmail.com wrote:

> Hi Mark
>
> Have you got any examples of documentation that would be good to migrate?
>
> Sounds great though
>
> Thanks
> Tim
>
> On Tue, 23 Jun 2020 at 22:39, Mark Waite  wrote:
>
>> The documentation team at CloudBees has asked if the community would be 
>> interested in reworking or adjusting documentation that CloudBees has 
>> created for their product to describe similar use cases on www.jenkins.io.   
>> The documentation team at CloudBees does not have the capacity to perform 
>> the transformation themselves, but would be happy to allow others to use 
>> their material, validate that it works with the most recent Jenkins LTS, 
>> update the screenshots to use Jenkins rather than the CloudBees product, 
>> and submit it as a pull request to the Jenkins documentation.
>>
>> I envision that the process would be similar to our Wiki migration 
>> process.  I think it would work something like this:
>>
>>- A CloudBees documentation team member creates a GitHub issue for 
>>content that could be reworked or reused on www.jenkins.io.  The 
>>GitHub issue provides the source text and images for reference or 
>> provides 
>>a link to a publicly accessible location that includes the source text 
>> and 
>>images
>>- A Jenkins contributor adds a comment to the GitHub issue that says, 
>>"I'm working on this"
>>- The Jenkins contributor uses the CloudBees ASCIIDOC, adjusts the 
>>phrasing as needed to apply to Jenkins, confirms that it works with 
>>Jenkins, and updates any screenshots to use Jenkins
>>- The Jenkins contributor adds an attribution to CloudBees (per the 
>>Creative Commons SA 4.0 license) to the bottom of the page submitted for 
>>www.jenkins.io
>>- The Jenkins contributor submits a pull request and the changes are 
>>reviewed in the usual pull request review process
>>
>> I believe the same process could be used by any company that delivers 
>> products based on Jenkins.
>>
>> Some of the questions that arise for me:
>>
>>- Is that type of process within the bounds of the www.jenkins.io 
>>licensing?
>>- Does this need a JEP or is it sufficient to discuss on the 
>>developers list?
>>- Are there any special approvals required for this type of content?
>>- Are there issues or concerns with the technique?
>>
>> Some questions that others might ask:
>>
>>- Why not just ask the CloudBees documentation team to submit the 
>>pull request to www.jenkins.io themselves?
>>
>>Their focus is on documenting their commercial product for their 
>>commercial customers.  They are willing to share their content with the 
>>Jenkins community, but they can't take the time to rework their content 
>> for 
>>use in the www.jenkins.io site.  If the community would like to use 
>>the content, they are welcome to do so
>>
>>- Who will review the pull requests and mentor the contributors?
>>
>>The same people that are currently reviewing pull requests will 
>>review these as well
>>
>> I'd like to discuss this here in the developers list with the assumption 
>> that if there are significant issues or questions, we work through them 
>> here on the list.  If we don't detect significant issues, then I'd bring 
>> the topic to a governance meeting to confirm that the Jenkins Board is OK 
>> with the idea.
>>
>> Thanks,
>> Mark Waite
>>
>> -- 
>> You received this message because you are subscribed to the Google Groups 
>> "Jenkins Developers" group.
>> To unsubscribe from this group and stop receiving emails from it, send an 
>> email to jenkinsci-de...@googlegroups.com.
>> To view this discussion on the web visit 
>> https://groups.google.com/d/msgid/jenkinsci-dev/b47ca50d-685d-4713-907c-adab5f5ba416n%40googlegroups.com
>>  
>> 
>> .
>>
>

-- 
You received this message because you are subscribed to the Google Groups 
"Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to jenkinsci-dev+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/jenkinsci-dev/9ba89778-2136-49ae-87ad-61d6329cf6ffn%40googlegroups.com.

Re: Contributing documentation from other sources

[Slide]

I concur with all of Oleg's statements. I think this sounds great, but we
need to make sure the content is not copyrighted in such a way that would
cause the Jenkins project issues.

On Wed, Jun 24, 2020 at 4:00 AM Oleg Nenashev 
wrote:

> Hi Mark,
>
> Thanks a lot for starting this discussion. I see no problem with such
> initiative in general. If someone is willing to donate the documentation
> content, it is always appreciated. There are many vendors and users who
> created their own documentation for Jenkins, and it would be great to see
> some of this documentation going to upstream and becoming available to all
> Jenkins users.
>
> Some notes about the implementation
>
>- We should ensure that contributors are not at risk of
>unintentionally violating the copyright. IMO all source content referenced
>in the created issues should have explicit Creative Commons license defined
>by the copyright owner. It applies to the text, screenshots and other
>media. It is not OK to require contributors to apply the new copyright
>during the transition
>- I do not think the migration will be just about "phrasing
>adjustments". The issues should be triaged before they become available for
>grabs (e.g. "needs-triage" label). An experienced documentation contributor
>(or a group of contributors) needs to take a look at the content to
>identify the migration feasibility and a correct migration destination. It
>is not just moving a page to another location, it will likely require a lot
>of content de-duplication. Also, some recommendations for CloudBees
>products may not directly apply to Jenkins which is more diverse in terms
>of the plugin/component ecosystem and supported use-cases
>- We have no standard way to put attributions to third parties in our
>documentation. Indeed we should do it according to the Creative Commons SA
>license. IMHO somebody needs to implement attribution support for pages and
>sections before such migration starts (metadata and some HAML patches?)
>
>
> I believe the same process could be used by any company that delivers
>> products based on Jenkins.
>>
> +1. Any contributions are welcome, including documentation content
> donations
>
>  Is that type of process within the bounds of the www.jenkins.io
>>  licensing?
>
> IMO Yes
>
> Does this need a JEP or is it sufficient to discuss on the developers list?
>
> I do not see a strict need in a JEP. Email discussion, dry-run, and
> creating "Content Donation Guidelines" in
> https://github.com/jenkins-infra/jenkins.io/blob/master/CONTRIBUTING.adoc 
> would
> be enough IMHO. Note that a similar process may apply to a donated plugin
> documentation. If you find having a process JEP helpful, +1 for having it.
> No need in extra overhead otherwise.
>
> Are there any special approvals required for this type of content?
>>
> It would be great to have at least one approval from a contributor not
> affiliated with a company donating documentation.
> IMHO we need a careful triage process, not a special review process here
>
> Best regards,
> Oleg
>
> On Wednesday, June 24, 2020 at 10:02:21 AM UTC+2, Tim Jacomb wrote:
>>
>> Hi Mark
>>
>> Have you got any examples of documentation that would be good to migrate?
>>
>> Sounds great though
>>
>> Thanks
>> Tim
>>
>> On Tue, 23 Jun 2020 at 22:39, Mark Waite  wrote:
>>
>>> The documentation team at CloudBees has asked if the community would be
>>> interested in reworking or adjusting documentation that CloudBees has
>>> created for their product to describe similar use cases on
>>> www.jenkins.io.   The documentation team at CloudBees does not have the
>>> capacity to perform the transformation themselves, but would be happy to
>>> allow others to use their material, validate that it works with the most
>>> recent Jenkins LTS, update the screenshots to use Jenkins rather than the
>>> CloudBees product, and submit it as a pull request to the Jenkins
>>> documentation.
>>>
>>> I envision that the process would be similar to our Wiki migration
>>> process.  I think it would work something like this:
>>>
>>>- A CloudBees documentation team member creates a GitHub issue for
>>>content that could be reworked or reused on www.jenkins.io.  The
>>>GitHub issue provides the source text and images for reference or 
>>> provides
>>>a link to a publicly accessible location that includes the source text 
>>> and
>>>images
>>>- A Jenkins contributor adds a comment to the GitHub issue that
>>>says, "I'm working on this"
>>>- The Jenkins contributor uses the CloudBees ASCIIDOC, adjusts the
>>>phrasing as needed to apply to Jenkins, confirms that it works with
>>>Jenkins, and updates any screenshots to use Jenkins
>>>- The Jenkins contributor adds an attribution to CloudBees (per the
>>>Creative Commons SA 4.0 license) to the bottom of the page submitted for
>>>www.jenkins.io
>>>- The Jenkins 

Re: Contributing documentation from other sources

[Oleg Nenashev]

Hi Mark,

Thanks a lot for starting this discussion. I see no problem with such 
initiative in general. If someone is willing to donate the documentation 
content, it is always appreciated. There are many vendors and users who 
created their own documentation for Jenkins, and it would be great to see 
some of this documentation going to upstream and becoming available to all 
Jenkins users. 

Some notes about the implementation

   - We should ensure that contributors are not at risk of 
   unintentionally violating the copyright. IMO all source content referenced 
   in the created issues should have explicit Creative Commons license defined 
   by the copyright owner. It applies to the text, screenshots and other 
   media. It is not OK to require contributors to apply the new copyright 
   during the transition
   - I do not think the migration will be just about "phrasing 
   adjustments". The issues should be triaged before they become available for 
   grabs (e.g. "needs-triage" label). An experienced documentation contributor 
   (or a group of contributors) needs to take a look at the content to 
   identify the migration feasibility and a correct migration destination. It 
   is not just moving a page to another location, it will likely require a lot 
   of content de-duplication. Also, some recommendations for CloudBees 
   products may not directly apply to Jenkins which is more diverse in terms 
   of the plugin/component ecosystem and supported use-cases
   - We have no standard way to put attributions to third parties in our 
   documentation. Indeed we should do it according to the Creative Commons SA 
   license. IMHO somebody needs to implement attribution support for pages and 
   sections before such migration starts (metadata and some HAML patches?)


I believe the same process could be used by any company that delivers 
> products based on Jenkins.
>
+1. Any contributions are welcome, including documentation content donations

 Is that type of process within the bounds of the www.jenkins.io licensing?

IMO Yes

Does this need a JEP or is it sufficient to discuss on the developers list?

I do not see a strict need in a JEP. Email discussion, dry-run, and 
creating "Content Donation Guidelines" in 
https://github.com/jenkins-infra/jenkins.io/blob/master/CONTRIBUTING.adoc would 
be enough IMHO. Note that a similar process may apply to a donated plugin 
documentation. If you find having a process JEP helpful, +1 for having it. 
No need in extra overhead otherwise.

Are there any special approvals required for this type of content?
>
It would be great to have at least one approval from a contributor not 
affiliated with a company donating documentation. 
IMHO we need a careful triage process, not a special review process here

Best regards,
Oleg

On Wednesday, June 24, 2020 at 10:02:21 AM UTC+2, Tim Jacomb wrote:
>
> Hi Mark
>
> Have you got any examples of documentation that would be good to migrate?
>
> Sounds great though
>
> Thanks
> Tim
>
> On Tue, 23 Jun 2020 at 22:39, Mark Waite  > wrote:
>
>> The documentation team at CloudBees has asked if the community would be 
>> interested in reworking or adjusting documentation that CloudBees has 
>> created for their product to describe similar use cases on www.jenkins.io.   
>> The documentation team at CloudBees does not have the capacity to perform 
>> the transformation themselves, but would be happy to allow others to use 
>> their material, validate that it works with the most recent Jenkins LTS, 
>> update the screenshots to use Jenkins rather than the CloudBees product, 
>> and submit it as a pull request to the Jenkins documentation.
>>
>> I envision that the process would be similar to our Wiki migration 
>> process.  I think it would work something like this:
>>
>>- A CloudBees documentation team member creates a GitHub issue for 
>>content that could be reworked or reused on www.jenkins.io.  The 
>>GitHub issue provides the source text and images for reference or 
>> provides 
>>a link to a publicly accessible location that includes the source text 
>> and 
>>images
>>- A Jenkins contributor adds a comment to the GitHub issue that says, 
>>"I'm working on this"
>>- The Jenkins contributor uses the CloudBees ASCIIDOC, adjusts the 
>>phrasing as needed to apply to Jenkins, confirms that it works with 
>>Jenkins, and updates any screenshots to use Jenkins
>>- The Jenkins contributor adds an attribution to CloudBees (per the 
>>Creative Commons SA 4.0 license) to the bottom of the page submitted for 
>>www.jenkins.io
>>- The Jenkins contributor submits a pull request and the changes are 
>>reviewed in the usual pull request review process
>>
>> I believe the same process could be used by any company that delivers 
>> products based on Jenkins.
>>
>> Some of the questions that arise for me:
>>
>>- Is that type of process within the bounds of the www.jenkins.io 
>>

Re: Contributing documentation from other sources

[Tim Jacomb]

Hi Mark

Have you got any examples of documentation that would be good to migrate?

Sounds great though

Thanks
Tim

On Tue, 23 Jun 2020 at 22:39, Mark Waite  wrote:

> The documentation team at CloudBees has asked if the community would be
> interested in reworking or adjusting documentation that CloudBees has
> created for their product to describe similar use cases on www.jenkins.io.
> The documentation team at CloudBees does not have the capacity to perform
> the transformation themselves, but would be happy to allow others to use
> their material, validate that it works with the most recent Jenkins LTS,
> update the screenshots to use Jenkins rather than the CloudBees product,
> and submit it as a pull request to the Jenkins documentation.
>
> I envision that the process would be similar to our Wiki migration
> process.  I think it would work something like this:
>
>- A CloudBees documentation team member creates a GitHub issue for
>content that could be reworked or reused on www.jenkins.io.  The
>GitHub issue provides the source text and images for reference or provides
>a link to a publicly accessible location that includes the source text and
>images
>- A Jenkins contributor adds a comment to the GitHub issue that says,
>"I'm working on this"
>- The Jenkins contributor uses the CloudBees ASCIIDOC, adjusts the
>phrasing as needed to apply to Jenkins, confirms that it works with
>Jenkins, and updates any screenshots to use Jenkins
>- The Jenkins contributor adds an attribution to CloudBees (per the
>Creative Commons SA 4.0 license) to the bottom of the page submitted for
>www.jenkins.io
>- The Jenkins contributor submits a pull request and the changes are
>reviewed in the usual pull request review process
>
> I believe the same process could be used by any company that delivers
> products based on Jenkins.
>
> Some of the questions that arise for me:
>
>- Is that type of process within the bounds of the www.jenkins.io
>licensing?
>- Does this need a JEP or is it sufficient to discuss on the
>developers list?
>- Are there any special approvals required for this type of content?
>- Are there issues or concerns with the technique?
>
> Some questions that others might ask:
>
>- Why not just ask the CloudBees documentation team to submit the pull
>request to www.jenkins.io themselves?
>
>Their focus is on documenting their commercial product for their
>commercial customers.  They are willing to share their content with the
>Jenkins community, but they can't take the time to rework their content for
>use in the www.jenkins.io site.  If the community would like to use
>the content, they are welcome to do so
>
>- Who will review the pull requests and mentor the contributors?
>
>The same people that are currently reviewing pull requests will review
>these as well
>
> I'd like to discuss this here in the developers list with the assumption
> that if there are significant issues or questions, we work through them
> here on the list.  If we don't detect significant issues, then I'd bring
> the topic to a governance meeting to confirm that the Jenkins Board is OK
> with the idea.
>
> Thanks,
> Mark Waite
>
> --
> You received this message because you are subscribed to the Google Groups
> "Jenkins Developers" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to jenkinsci-dev+unsubscr...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/jenkinsci-dev/b47ca50d-685d-4713-907c-adab5f5ba416n%40googlegroups.com
> 
> .
>

-- 
You received this message because you are subscribed to the Google Groups 
"Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to jenkinsci-dev+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/jenkinsci-dev/CAH-3Bie9y2fE4BxqneF6U-A%3D%3DSUkyrior6ZqL4YZNuoN1sqPew%40mail.gmail.com.

Contributing documentation from other sources

[Mark Waite]

The documentation team at CloudBees has asked if the community would be 
interested in reworking or adjusting documentation that CloudBees has 
created for their product to describe similar use cases on 
www.jenkins.io.   The documentation team at CloudBees does not have the 
capacity to perform the transformation themselves, but would be happy to 
allow others to use their material, validate that it works with the most 
recent Jenkins LTS, update the screenshots to use Jenkins rather than the 
CloudBees product, and submit it as a pull request to the Jenkins 
documentation.

I envision that the process would be similar to our Wiki migration 
process.  I think it would work something like this:

   - A CloudBees documentation team member creates a GitHub issue for 
   content that could be reworked or reused on www.jenkins.io.  The GitHub 
   issue provides the source text and images for reference or provides a link 
   to a publicly accessible location that includes the source text and images
   - A Jenkins contributor adds a comment to the GitHub issue that says, 
   "I'm working on this"
   - The Jenkins contributor uses the CloudBees ASCIIDOC, adjusts the 
   phrasing as needed to apply to Jenkins, confirms that it works with 
   Jenkins, and updates any screenshots to use Jenkins
   - The Jenkins contributor adds an attribution to CloudBees (per the 
   Creative Commons SA 4.0 license) to the bottom of the page submitted for 
   www.jenkins.io
   - The Jenkins contributor submits a pull request and the changes are 
   reviewed in the usual pull request review process

I believe the same process could be used by any company that delivers 
products based on Jenkins.

Some of the questions that arise for me:

   - Is that type of process within the bounds of the www.jenkins.io 
   licensing?
   - Does this need a JEP or is it sufficient to discuss on the developers 
   list?
   - Are there any special approvals required for this type of content?
   - Are there issues or concerns with the technique?
   
Some questions that others might ask:

   - Why not just ask the CloudBees documentation team to submit the pull 
   request to www.jenkins.io themselves?
   
   Their focus is on documenting their commercial product for their 
   commercial customers.  They are willing to share their content with the 
   Jenkins community, but they can't take the time to rework their content for 
   use in the www.jenkins.io site.  If the community would like to use the 
   content, they are welcome to do so
   
   - Who will review the pull requests and mentor the contributors?
   
   The same people that are currently reviewing pull requests will review 
   these as well
   
I'd like to discuss this here in the developers list with the assumption 
that if there are significant issues or questions, we work through them 
here on the list.  If we don't detect significant issues, then I'd bring 
the topic to a governance meeting to confirm that the Jenkins Board is OK 
with the idea.

Thanks,
Mark Waite

-- 
You received this message because you are subscribed to the Google Groups 
"Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to jenkinsci-dev+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/jenkinsci-dev/b47ca50d-685d-4713-907c-adab5f5ba416n%40googlegroups.com.