New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merging community documentation into sensuapp.org/docs #58

Closed
mbbroberg opened this Issue Sep 28, 2017 · 17 comments

Comments

Projects
None yet
4 participants
@mbbroberg
Member

mbbroberg commented Sep 28, 2017

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:

screen shot 2017-09-28 at 9 54 34 am

screen shot 2017-09-28 at 9 54 51 am

@majormoses

This comment has been minimized.

Show comment
Hide comment
@majormoses

majormoses Sep 28, 2017

Member

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.

Member

majormoses commented Sep 28, 2017

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

This comment has been minimized.

Show comment
Hide comment
@mbbroberg

mbbroberg Sep 29, 2017

Member

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 😂

Member

mbbroberg commented Sep 29, 2017

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

This comment has been minimized.

Show comment
Hide comment
@majormoses

majormoses Sep 30, 2017

Member

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.

Member

majormoses commented Sep 30, 2017

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 added a commit to sensu-plugins/sensu-plugins.github.io that referenced this issue Oct 6, 2017

Simplifying and linking to new efforts
Relates to sensu-plugins/community#58

Simplifying the messaging here so people know what to expect and the basics of getting involved. Would love to get people filtering into GitHub to help on the future.

mbbroberg added a commit to sensu-plugins/sensu-plugins.github.io that referenced this issue Oct 6, 2017

Simplifying and linking to new efforts
Relates to sensu-plugins/community#58

Simplifying the messaging here so people know what to expect and the basics of getting involved. Would love to get people filtering into GitHub to help on the future.

mbbroberg added a commit to sensu-plugins/sensu-plugins.github.io that referenced this issue Oct 6, 2017

Simplifying and linking to new efforts
Relates to sensu-plugins/community#58

* Simplifying the messaging here so people know what to expect and the basics of getting involved. Would love to get people filtering into GitHub to help on the future.
* Also removing nonexistent layout type from `_docs/overview.md`

majormoses added a commit to sensu-plugins/sensu-plugins.github.io that referenced this issue Oct 16, 2017

Simplifying and linking to new efforts
Relates to sensu-plugins/community#58

* Simplifying the messaging here so people know what to expect and the basics of getting involved. Would love to get people filtering into GitHub to help on the future.
* Also removing nonexistent layout type from `_docs/overview.md`
@mbbroberg

This comment has been minimized.

Show comment
Hide comment
@mbbroberg

mbbroberg Nov 8, 2017

Member

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

Member

mbbroberg commented Nov 8, 2017

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

@mbbroberg mbbroberg referenced this issue Nov 8, 2017

Closed

Create Best Practices Document for testing #46

3 of 3 tasks complete

@mbbroberg mbbroberg changed the title from Merging sensu-plugins.io into sensuapp.org/docs to Merging community documentation into sensuapp.org/docs Dec 14, 2017

@mbbroberg

This comment has been minimized.

Show comment
Hide comment
@mbbroberg

mbbroberg Dec 20, 2017

Member

Two things:

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
Member

mbbroberg commented Dec 20, 2017

Two things:

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

This comment has been minimized.

Show comment
Hide comment
@obfuscurity

obfuscurity Jan 12, 2018

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

obfuscurity commented Jan 12, 2018

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

@mbbroberg

This comment has been minimized.

Show comment
Hide comment
@mbbroberg

mbbroberg Jan 12, 2018

Member

@cwjohnston could you provide an update?

Member

mbbroberg commented Jan 12, 2018

@cwjohnston could you provide an update?

@cwjohnston

This comment has been minimized.

Show comment
Hide comment
@cwjohnston

cwjohnston Jan 30, 2018

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.

cwjohnston commented Jan 30, 2018

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

This comment has been minimized.

Show comment
Hide comment
@mbbroberg

mbbroberg Feb 5, 2018

Member

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!

Member

mbbroberg commented Feb 5, 2018

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

This comment has been minimized.

Show comment
Hide comment
@mbbroberg

mbbroberg Mar 20, 2018

Member

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!

Member

mbbroberg commented Mar 20, 2018

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

This comment has been minimized.

Show comment
Hide comment
@majormoses

majormoses Mar 20, 2018

Member

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.

Member

majormoses commented Mar 20, 2018

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

This comment has been minimized.

Show comment
Hide comment
@majormoses

majormoses Apr 2, 2018

Member

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.

Member

majormoses commented Apr 2, 2018

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

This comment has been minimized.

Show comment
Hide comment
@mbbroberg

mbbroberg Apr 3, 2018

Member

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 ❤️

Member

mbbroberg commented Apr 3, 2018

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

This comment has been minimized.

Show comment
Hide comment
@majormoses

majormoses Apr 3, 2018

Member

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.

Member

majormoses commented Apr 3, 2018

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.

@sensu-plugins sensu-plugins locked and limited conversation to collaborators Apr 3, 2018

@majormoses

This comment has been minimized.

Show comment
Hide comment
@majormoses

majormoses Apr 6, 2018

Member

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.

Member

majormoses commented Apr 6, 2018

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.

@sensu-plugins sensu-plugins unlocked this conversation May 3, 2018

@mbbroberg

This comment has been minimized.

Show comment
Hide comment
@mbbroberg

mbbroberg May 3, 2018

Member

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

Member

mbbroberg commented May 3, 2018

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

@mbbroberg

This comment has been minimized.

Show comment
Hide comment
@mbbroberg

mbbroberg Jun 29, 2018

Member

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 💪 🙌

Member

mbbroberg commented Jun 29, 2018

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 💪 🙌

@mbbroberg mbbroberg closed this Jun 29, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment