Jenkins : Jenkins Documentation Needs

Summary: The biggest single problem with the Jenkins.IO documentation page – the conclusion suggested when each of the gaps described in the table below is considered in the aggregate – is that the layout and content of that web page currently suggest that it is little more than a placeholder for hyperlinks that one or two stakeholders thought might be applicable.

Upgrades to content linked from that page, and layout of that page itself, can close the gap.

Note Jenkins.IO does not have an embedded search function.

The working assumption that underpins “Desired Future State” is that the product usage arc from installation to deployment should be clear for both novice and experienced Jenkins users.

Gap comments are bucketed into three general areas:
Layout
Content
Orthography (word usage)

Current State

Desired State

Layout Issues

Documentation landing page has no visible tie to Jenkins.IO site

Banner, icons, and graphical elements mirror those on Jenkins.IO site

“Pipeline” is first heading on Doc page but has no context

Short explanation of pipeline lends context to heading; pipeline is not (necessarily) only functionality singled out

“Pipeline” and “Handbook” at same heading level

Page layout is more horizontal than vertical

“Handbook” and “Chapters” (in the handbook) at same heading level

Concatenate the Handbook and Chapters headings (use just one)

LTS Upgrade Guide heading has no context (and no LTS definition)

Release explanation contrasts latest with LTS

“Developer docs” flagged midway down the page, but what’s above them? User docs are not identified as such, and it’s not clear that all of the linked material isn’t aimed at developers

“For Users” and “For Developers” as headings (or something similar)

“Javadocs” and “LTS baselines” would be more intuitive formatted as a two-column table but Javadocs is a misleading heading because what matters is latest vs. LTS; they’re all Javadocs

New “Jenkins Releases” heading accommodates both latest and LTS with a definition for each

“Getting Started with Pipeline” and “Getting Started with Jenkins” are not grouped together

Getting Started (i.e., Quick Start) material should be together

“Best Practices” buried as chapter 4 of the Handbook

“Best Practices” should be standalone section with subheadings (best practices for these things)

Content Issues

No mention of or link to Blue Ocean

Link to Blue Ocean landing page

Only one implied division between personas (user and developer are represented, but user is currently only by implication)

personas: Novice, Intermediate, Advanced

“Best Practices” does not link to any best practices

Best Practices actually exist

“Pipeline” is chapter 5 of the Handbook, but also a heading in its own right.

All pipeline links should be in the same section

Missing “Declarative Pipeline” information (and contrast with “Scripted Pipeline”)

Getting Started with Pipeline should explain the difference

Pipeline user documentation does not yet incorporate new stage, lock, and milestone usage

First link to blog entry about stage, lock, and milestone, then incorporate blog contents into user docs.

No mention of integration (with plugins or platforms)

Assuming there is a use case for integration, that info should be surfaced

No reference to Troubleshooting

Some troubleshooting (Such as how to select EC2 instance types when you run Jenkins in AWS environment?)

No readily accessible “global library” usage information

Global library information situated in pipeline context, likely using globral library docs by Jesse Glick as source material

“Scaling Jenkins” chapter of handbook is just a placeholder

This should have actual information about how to scale Jenkins

Jenkins Installation and Setup is accessed through Download page

Jenkins Installation and Setup should be up top on the Documentation landing page