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 |