Suggestion: documentation as part of the plugin under SCM

[Rafael Rezende]

We have a growing number of Jenkins plugins in our company's repository. They are all for specific purposes, reason why there is no plan to release them in public repository any time soon (plus legal issues :-( shame).
Anyway, we had plugin docs scattered all over our departments worldwide until we decided to provide a central confluence and a template plugin in which the URL is set to a generated page. We still don't have 100% of adoption, but the culture is growing...

Another issue as to keep sync between the documentation and the plugin version. Confluence has this nasty thing of assigning a fix id to the latest version of the page. So, if you want to get a permanent id for the current page, you actually have to bump the page version once, get the fixed id from the history etc... Plus, there is no mapping between plugin version and the corresponding documentation for that release.

For the reasons above, I was thinking about introducing the documentation in markdown format directly from the Jenkins plugin itself. That is, an extra doc folder in the plugin's source that will be part of the snapshot (tag, revision, release.. you name it). This way, there is a direct correlation between the source and the doc, devs feel motivated (or compelled) to update docs accordingly, and I can generate the pages automatically saving people the trouble of managing confluence pages.

I'm suggesting it here because not long ago you established that plugins without documentation in your confluence are to be considered deprecated. So, maybe providing the template doc with the plugin (in your maven template skeleton, for example) might be the next step.

[Manfred Moser]

On the TFS plugin we recently moved out docs to the github code repo as a readme .

https://github.com/jenkinsci/tfs-plugin

And if you want to get more fancy you could easily create a documentation site with the maven site plugin and writing the docs themselves in markdown or asciidoc. E.g. check out my android-maven-plugin site.. all written in asciidoc.

http://simpligility.github.io/android-maven-plugin/

You can go further and style it if you want as well. And of course you can host it anywhere since its just a static site. In this case its just hosted with github pages.. 

Manfred

--
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/3f43f737-27ea-4f3f-b9e4-e3a466cd0ae5%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Jesse Glick]

On Wed, Mar 9, 2016 at 11:13 AM, Rafael Rezende <rafael...@gmail.com> wrote:
> I was thinking about introducing the documentation in
> markdown format directly from the Jenkins plugin itself. That is, an extra
> doc folder in the plugin's source that will be part of the snapshot (tag,
> revision, release.. you name it). This way, there is a direct correlation
> between the source and the doc, devs feel motivated (or compelled) to update
> docs accordingly

That is what I did in `workflow-plugin`, for reasons similar to those
you outline.

There was some discussion about this topic in the context of the
Jenkins 2.0 website. I was not really involved but IIRC there was
general agreement that it would be nice to have plugin documentation
maintained (a) in markup in SCM, rather than in a wiki, (b) in
per-plugin repositories rather than globally (meaning that the site
would somehow suck in conventionally-named files from other
repositories). Someone involved in this work should fill in details.

> you established that plugins
> without documentation in your confluence are to be considered deprecated.

I think the rule was that they had to *have* a wiki page, and use that
as the `<url>` in `pom.xml`. But the wiki could merely be a stub
linking to the real docs.

[Rafael Rezende]

@Manfred, great hint about the maven site plugin. I remember using it for another format in the past, but just got to know that it actually supports Markdown since release 3.3. First I though about using jekyll, just like GitHub. But the maven site plugin would be better integrated. Thanks!

@Jesse, I'll probably end up with a stub confluence page internally also, though I can foresee some resistance :-) btw, is there any documentation about the Jenkins release process behind the scenes? For example, when someone wants to contribute with a new plugin, a whole environment is created around it (github repo, confluence page, a jenkins job to build the plugin, Jira etc). Is everything triggered by scripts?

[Jesse Glick]

On Wed, Mar 9, 2016 at 12:11 PM, Rafael Rezende <rafael...@gmail.com> wrote:
> is there any documentation
> about the Jenkins release process behind the scenes? For example, when
> someone wants to contribute with a new plugin, a whole environment is
> created around it (github repo, confluence page, a jenkins job to build the
> plugin, Jira etc). Is everything triggered by scripts?

https://wiki.jenkins-ci.org/display/JENKINS/IRC+Bot

is used by admins to create the GitHub repo and JIRA component. Wiki
page creation is up to the plugin creator (be sure to add beneath the
Plugins page, add one or more `plugin-*` tags, and include the macro
that produces plugin summary information—view source of another plugin
page to see). The Jenkins job is created automatically.

[Oleg Nenashev]

Hi,

Personally I'm +1 on moving to GitHub. Confluence is error-prone and unstable. It also has capture/spam problems.
So such migration may solve all the issues and allow to keep docs up to date.

FYI we also keep the documentation centralization in mind.
E.g. there is a project idea for GSoC2016, which covers publishing of the documentation to the Jenkins website.
It should solve the usage limitations for common users.

BR, Oleg

среда, 9 марта 2016 г., 21:36:38 UTC+1 пользователь Jesse Glick написал:

[Cynthia Anyango]

@Oleg , in you opinion how can the documentation centralization be achieved ?