Merging community documentation into sensuapp.org/docs

[mbbroberg]

Update: Dec 20

The new framework for documentation is visible here with source at sensu/sensu-docs-site. It includes the documentation listed below. We will check off each page once it's reviewed by any contributor -- please add a comment if you've reviewed a page!

Background

There's an effort at Team Sensu to get out of the middleman website that takes 30+ minutes to build to a faster, better organized and searchable Hugo service that was previewed at Sensu Summit. In this new build, there will be a section for Plugins specifically.

Proposal

I'd like to review existing documentation on http://sensu-plugins.io/docs (found in markdown here), decide if any pages should be deleted and which ones should be updated for migration. We can check off each document as we decide what to do with it.

• FAQ.md - updated 3 months ago
• Roadmap.md - updated 2 years ago
• b_and_r.md - updated 5 months ago
• developer_guidelines.md - updated 3 months ago
• getting_started.md - updated 2 years ago
• gsoc15.md - updated 2 years ago
• installation_instructions.md - updated 2 years ago
• overview.md - updated 2 years ago
• testing.md - updated 2 years ago
• tom_servo.md - updated 2 years ago

Example of the upcoming redesign:

[majormoses]

Great idea, we definitely could use some major facelifts for exploring documentation. One minor nitpick: please use 302, 303, or 307 HTTP status codes over something permanent like a 301 or 308. I have found more than once in a situation where I wish it had been temporary but did a permanent redirect.

[mbbroberg]

Should these docs be reviewed from the github.io _docs folder or from https://github.com/sensu-plugins/documentation? I just realized we have both 😂

[majormoses]

I have always referred to the https://github.com/sensu-plugins/documentation one. They both pre-date me and I'd like it to be consolidated into one place.

[mbbroberg]

First draft of this migration is completing soon so flagging appropriately!

[mbbroberg]

Two things:

• Pages from site are officially merged into the new docs site: https://github.com/sensu/sensu-docs-site, which is targeted to Soft Launch on Feb 1
• The sensuapp.org/docs pages will remain separate until the Launch milestone is hit, tracked here: https://github.com/sensu/sensu-docs-site/milestones

A reminder of why we're doing this direction - this new site is a place for:

• Versioned documentation that loads fast and has full-text search
• Easier contribution experience with more sane organization and a site runnable on its own

[obfuscurity]

How are things coming along afa meeting the Feb 1 deadline?

[mbbroberg]

@cwjohnston could you provide an update?

[cwjohnston]

How are things coming along afa meeting the Feb 1 deadline?

The soft-launch milestone, due Feb 1, is being tracked here. We're getting close to complete, although there are a few outstanding issues that I need to coordinate with folks, @mbbroberg in particular.

[mbbroberg]

A few notes as I think through new docs:

• Redirects from sensu-plugins.io -> docs.sensu.io as we redesign the website will be clutch 👌
• A landing page called Maintainers that consumes a good bit of our maintainer practices from here
• A landing page for Contributors that takes on the contributor guidelines and some context from our README
• A landing page for users as well for getting started and links to best practices docs

Feeling excited about our progress!

[mbbroberg]

So so happy to say we have a proper docs site: https://docs.sensu.io

It also has a section just for Plugins: https://docs.sensu.io/plugins/2.3/

There are some known inaccuracies so far:

• The version (2.3) doesn't quite make sense
• Docs are out of date there (since they're clones of the inaccurate ones we've had)

I invite anyone who has time to get involved to start to comment here. Thanks!

[majormoses]

I think we need an unversioned set of docs for plugins as I don't see any versioning scheme that makes sense for generic plugin docs. There might be need later if we ever want to have better per plugin docs but I think that should honestly still live in the repo.

[majormoses]

I spoke with @mbbroberg about this: until privs are granted to the community maintainers no further effort will be made to consolidate and fixup docs in the new location.

[mbbroberg]

I understand your preference to wait majormoses. So others know, PRs are welcome right now by whomever has time and interest in participating the effort at this early phase ❤️

[majormoses]

I have spoken to several maintainers on plugins on this and we collectively are not considering the new docs site the source of truth (for plugins) until we have been granted access. We have scheduled an internal meeting to hash this out but for now all changes for plugins documentation should remain in their old location until we can reach an agreement on how to proceed.

[majormoses]

We spoke about this some more and privileges have been granted. I have started on updating documentation and will report back when I have a first pass PR.

[mbbroberg]

We did a thing! Got toward a space where we can move on without most of the cruft: sensu/sensu-docs#392

[mbbroberg]

The PR above is merged, completing what I hoped to see in this card. I would say the sensu-plugins.io redirects will be a full up item that doesn't need to be in scope here. I'll move that to a Maintainer issue given only that group has access to DNS records.

Thanks everyone for all the support and good ideas along the way 💪 🙌