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

[Tim Jacomb]

Hi Mark

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

Sounds great though

Thanks

Tim

--
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.

[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

To unsubscribe from this group and stop receiving emails from it, send an email to jenkin...@googlegroups.com.

[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.

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/d8744ab0-29fb-46b3-844c-f94911979fb8o%40googlegroups.com.

--

Website: http://earl-of-code.com

[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

[Jesse Glick]

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