Skip to content
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
Closed

Merging community documentation into sensuapp.org/docs #58

mbbroberg opened this issue Sep 28, 2017 · 17 comments

Comments

@mbbroberg
Copy link
Contributor

@mbbroberg 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
Copy link
Member

@majormoses 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
Copy link
Contributor Author

@mbbroberg 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
Copy link
Member

@majormoses 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
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
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
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
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
Copy link
Contributor Author

@mbbroberg mbbroberg commented Nov 8, 2017

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

@mbbroberg mbbroberg mentioned this issue Nov 8, 2017
3 of 3 tasks complete
@mbbroberg mbbroberg changed the title Merging sensu-plugins.io into sensuapp.org/docs Merging community documentation into sensuapp.org/docs Dec 14, 2017
@mbbroberg
Copy link
Contributor Author

@mbbroberg 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
Copy link

@obfuscurity obfuscurity commented Jan 12, 2018

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

@mbbroberg
Copy link
Contributor Author

@mbbroberg mbbroberg commented Jan 12, 2018

@cwjohnston could you provide an update?

@cwjohnston
Copy link
Contributor

@cwjohnston 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
Copy link
Contributor Author

@mbbroberg 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
Copy link
Contributor Author

@mbbroberg 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
Copy link
Member

@majormoses 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
Copy link
Member

@majormoses 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
Copy link
Contributor Author

@mbbroberg 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
Copy link
Member

@majormoses 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
Copy link
Member

@majormoses 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
Copy link
Contributor Author

@mbbroberg 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
Copy link
Contributor Author

@mbbroberg 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
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants
You can’t perform that action at this time.