Merge RubyGems Guides and Bundler Website Guides

[SandNerd]

I also noticed that I couldn't search on in RubyGems Guides while it possible on Bundler website. Hope that's a feature we gain.

[coilysiren]

Thoughts on this (after talking with @indirect)

1. it's unclear if the amount of work this would take is worth the gain
2. it's unclear if users will expect the gem and bundle commands to be on different websites
3. we would not want to start on this until after Bundler+RubyGems 3.0. Bundler is currently at 1.13.

thanks so much for the thought provoking issue @sahal2080!

[duckinator]

Talked to @indirect about this on Slack and decided a good first step would be collecting a list of all of the guides on both http://guides.rubygems.org and http://bundler.io and organizing those, so we know what we want the website to eventually have.

Unless we decide to merge them immediately, the second step would be to cross-reference.

@indirect linked to https://jacobian.org/writing/what-to-write/ and https://jacobian.org/writing/great-documentation/, and mentioned that the "three categories of docs" (see the first of those two links) may be useful for organizing.

[duckinator]

I'm creating a spreadsheet of all of the guides on both http://guides.rubygems.org and http://bundler.io/docs.html, and labeling each as being one of the three categories mentioned in the post I mentioned in my last comment — tutorials, overviews, reference material.

[indirect]

:tada:

[duckinator]

We have 70 guides, references, etc total between RubyGems and Bundler.

• 15 RubyGems tutorials and overviews
• 4 RubyGems command/specification/API references
• 15 Bundler tutorials and overviews
• 21 Bundler command references
• 14 Bundler release notes

Spreadsheet: https://docs.google.com/spreadsheets/d/1YfGKgIGJU_sJL03PwMClStEgH-LNLxq10w7y6Dbuat4/edit?usp=sharing

The Bundler documentation is really impressive.

[SandNerd]

In addition to the articles above I'd like to add The 8 Types of Technical Documentation and Why Each Is Important.

It'd be also nice if we have a place where anyone can post links of articles that to be considered for inclusion in the official documentation or maybe just referred to. I suggest a gist or something similar to those Awesome lists so anyone can fork it, add content but keep the maintainer in control.

[indirect]

keeping a list like that is a great idea! unfortunately the link to 8 types of documentation just produces a bunch of encoding error gibberish for me :(

[SandNerd]

That was the intended effect as it's the first step into infecting RubyGem's maintainers PCs with my virus and from there all gems in the universe! Darn it I blew it again with my big mouth.

In case you haven't already done so, this is the archive.org version: https://web.archive.org/web/20160412123621/http://www.rhyous.com/2011/07/21/the-different-types-of-technical-documentation-for-software-and-why-each-is-important/

[deivid-rodriguez]

I'm really missing the Search and Auto-Anchor features of the Bundler site at guides.rubygems.org.

I think a solution that does not involve a big amount of work would be to move RubyGems guides to be one of the guides in this list here and then redirect there from guides.rubygems.org?

[indirect]

Yeah, sounds reasonable to me for now!

On May 9, 2022, at 11:14 AM, David Rodríguez @.***> wrote:

I'm really missing the Search and Auto-Anchor features of the Bundler site at guides.rubygems.org.

I think a solution that does not involve a big amount of work would be to move RubyGems guides to be one of the guides in this list here https://bundler.io/v2.3/guides/faq.html and then redirect there from guides.rubygems.org?

— Reply to this email directly, view it on GitHub https://github.com/rubygems/guides/issues/164#issuecomment-1121422007, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAAATS5ND3J6KZZ4VK27ELVJFIYJANCNFSM4CRQUPSA. You are receiving this because you were mentioned.

[duckinator]

Sounds good to me as well. 👍