Improvements to the developer docs

[Daniel Beck]

Hi everyone,

I'm looking into improving the developer documentation for Jenkins. I'm not going to be able to do an entire rewrite of the docs, but if you have specific issues with the docs you think should be improved, please let me know. What parts do you think are documented insufficiently?

This should preferably be issues with getting the 'big picture', interaction/relation of different parts, discovering available APIs, etc. -- things not as easily done in Javadoc, but if you see major problems with these, add them to the list.

I'm also specifically inviting less experienced core/plugin developers to provide suggestions. What are/were you struggling with the most? What documentation would you have liked to find but couldn't?

Daniel

[Brian Adriance]

Hi Daniel,

 

I found that learning Jelly and how Jelly, descriptors, and instances all work together was a bit frustrating. If there were more examples that described why or how the code does what it does, that’d probably be a good thing. GitHub already gives us the what, but through that vehicle we are given many options and not really any one best-practice.

 

So if there were anything I’d like to see for future plugin developers, it’d be a larger set of “here’s an example of making a xyz, and why it is the way it is”.

 

Good luck!

-Brian

--
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/52690EB6-1E39-4248-A46A-2124822FD162%40beckweb.net.
For more options, visit https://groups.google.com/d/optout.

[John Tatum]

It seems like I had trouble finding good information about entry points. It also did not seem like there were any references to the javadoc from the wiki(I always found what I needed using google).

Also, it seems like there are some significant sources of information about plugins and such that are not really mentioned. For example, back in October you commented on https://github.com/jenkinsci/ssh-plugin/pull/9#issuecomment-121570158 with several significant insights about how the plugin was being used and how changes under consideration would impact the user base. Where did that information come from? Another example would be https://wiki.jenkins-ci.org/display/JENKINS/Plugin+Report+Card, which I do not recall ever seeing any mention of until somebody mentioned it on the mail list.

Those are just two examples, but I would say anything that can help developers understand how plugins(and core) are used and what the potential impact of changes would be is going to be incredibly helpful.


John Tatum
john....@live.com
http://scientifichooliganism.net

Although this e-mail and any attachments are believed to be free of any virus or other defect that might affect any computer system into which it is received and/or upon which it is opened, it is the responsibility of the recipient(s) to ensure that it is virus and/or defect free and John Tatum bears no responsibility for any loss and/or damage arising in any way from its use.

> From: m...@beckweb.net
> Subject: Improvements to the developer docs

[Daniel Beck]

On 17.07.2015, at 01:13, John Tatum <john....@live.com> wrote:

> It seems like I had trouble finding good information about entry points.

What do you mean by entry points? The ExtensionPoint/@Extension mechanism? The Plugin class? @Initializer? Stapler request routing? Jelly views/st:include?

> It also did not seem like there were any references to the javadoc from the wiki(I always found what I needed using google).

Is this related to using the Script Console? I'm asking because, when writing plugins you should be able to configure your IDE to download and display the Javadoc for Jenkins, so you should need the Javadoc on the web less.

[Jochen A. Fuerbacher]

Hi there,

I'd like to see much more documentation about Jelly, because I had some trouble with it. It also would be great to see some Groovy documentation.

A structured overview of how to extend job configuration (JobProperty, ...) and global configuration (Discriptor, ...) would be great to have for beginners.

Thank you.

Jochen

 

Von: Daniel Beck <m...@beckweb.net>

Betreff: Improvements to the developer docs

Datum: 16. Juli 2015 14:31:48 MESZ

An: jenkin...@googlegroups.com

Antwort an: jenkin...@googlegroups.com

[domi]

one thing I never really got my head around was the API of the folders plugin.
Many plugins could really improve if they would integrate properly with the folders plugin - but every time I started this, I gave up because it was not obvious how to do this.
e.g. how to implement a config hierarchy on different levels:
- global
- folder
- user
- job

Domi

> --
> 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/5048EC38-1E29-403B-88C1-290013F45FCE%40beckweb.net.

[Kanstantsin Shautsou]

1) As person that has INFRA access: update confluence. This is the blocker for me for any docs activities.

2) Review/re-organise/clean-up current docs (they are duplicated in many places because people can't find right page and creating new).

3) Stop living in workflow only world https://github.com/jenkinsci/workflow-plugin/commit/b127fd48c37ed034d5d04d62d10d3de8136e04f3#commitcomment-11916805 

[John Tatum]

I mean Extension Points. They are documented on the wiki, but again, I discovered them through the mailing list instead of being referenced to them from elsewhere in the documentation.

The reference to the Javadoc is not in relation to the script console. Not everybody uses an IDE for development.

John Tatum
john....@live.com
http://scientifichooliganism.net

Although this e-mail and any attachments are believed to be free of any virus or other defect that might affect any computer system into which it is received and/or upon which it is opened, it is the responsibility of the recipient(s) to ensure that it is virus and/or defect free and John Tatum bears no responsibility for any loss and/or damage arising in any way from its use.

> Subject: Re: Improvements to the developer docs
> From: m...@beckweb.net
> Date: Fri, 17 Jul 2015 07:05:51 +0200
> To: jenkin...@googlegroups.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-de...@googlegroups.com.

> To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/5048EC38-1E29-403B-88C1-290013F45FCE%40beckweb.net.

[Kanstantsin Shautsou]

On Saturday, July 18, 2015 at 1:35:24 AM UTC+3, John Tatum wrote:

I mean Extension Points. They are documented on the wiki, but again, I discovered them through the mailing list instead of being referenced to them from elsewhere in the documentation.

1) Current confluence version doesn't clearly show pages structure.  https://wiki.jenkins-ci.org/display/JENKINS/Extend+Jenkins?showChildren=true#children 

2) It also listed in TOC on https://wiki.jenkins-ci.org/display/JENKINS/Extend+Jenkins . When i started developing jenkins and plugins i spent some time reading all info starting from this page (that is expected entry point). 

Probably review 'site map' on wiki to get better understanding how documentation is organised.

[Jesse Glick]

On Thu, Jul 16, 2015 at 8:31 AM, Daniel Beck <m...@beckweb.net> wrote:
> What parts do you think are documented insufficiently?

The relationship between `Describable` and `Descriptor`, and how you
are *supposed* to do form binding (recommended idioms as in
`ui-samples-plugin`).

[oliver gondža]

That reminds me, quite some time ago I started a repo[1] with example
extension point implementations for the purposes of a workshop. Not sure
it is of any use for this purpose ...

[1] https://github.com/jenkinsci/sample-extensions

--
oliver