Put the docs back!

[zachgrayio]

I recently discovered that the documentation has been removed in favor of a third-party site in this commit.

While I applaud this as a clever SEO strategy on the part of the consultant, this is just a net negative for everyone else, and I'm frankly surprised to see this kind of change coming through to repos hosted under bazelbuild. I understand that this is no longer maintained by Google, but even still... 🤦

I'm all for improving the docs for bazelbuild projects but this is clearly the wrong direction.

Revert #652

[UebelAndre]

Sorry the change to the docs upset you! But I thought all the docs and previously links were still valid and active. Can you elaborate more on how this commit impacted you?

[zachgrayio]

I think the diff really speaks for itself here honestly, but sure.

As you are aware, it's a common practice to keep the WORKSPACE rule boilerplate necessary to add the ruleset to a project, and in many cases even a minimal BUILD example inline in the README, typically right up at the top. Of course, this is what the ruleset did previously. I think out of all of the bazelbuild rulesets there's maybe 1-2 which do not follow this pattern, and even these typically link to the stardoc generated docs hosted directly in the repo's github.io static site and not externally; something I would imagine would be the first and best choice in this situation.

What's even more curious is that even the high-level description of the ruleset's features has been removed from the README in favor of the generated content hosted externally and buried under a link which is both easy to miss and hosted on an unfamiliar site with unknown uptime/availability, not to mention operated by a for-profit third-party. Not a good look.

As I said previously, I'm all for using the tooling to generate docs here and generally supportive of anything that makes any of the rulesets easier to discover and work with, and clearly there are improvements to be made in this area across most rulesets, but this is pretty clearly worsening the UX rather than improving it in ways that again are pretty obvious, but to flag some quickly:

• you've removed the high level description of what the rules even can do from the README
• even basic installation instructions now require the user to parse the whole page upon the violation of their expectations to find installation/usage instructions readily available at the top
• now, the most prominent candidate for installation instructions is the examples directory (closest to the top) and doesn't contain the convenience WORKSPACE rule snippet most users are looking for
• the call-to-action to link out of github to find the installation/usage examples is buried at the bottom and the microcopy is misleading and dismissible (sounds like internal documentation; users are looking for installation instructions)
• at a glance the project looks much less supported/viable; in this ecosystem, repos that don't put easy installation and usage examples front-and-center are often not in a good state
• you've ruined your project's SEO and now the ruleset will be harder to find. ironically (intentionally?) the consultant's site will now eventually outrank you on your own search terms, in addition to getting a boost via all the new backlinks generated whenever the repo is cloned, at your expense

A summary of the issues that affect all would-be users, especially those who are newer to bazel (probably the majority of the users of this ruleset hoping to build legacy/non-bazel cc due to the fact they're in the process of evaluating/adopting):

1: Any divergence from content inlined into the README is a downgrade on UX & SEO; at a minimum, description and installation should be restored, even if doc gen is in place
2: Linking out to an external third-party is a further issue; when that company is literally selling something to the audience who is now driven there explicitly to find even a description of the repo, it's beginning to look like a pretty unhealthy project

[UebelAndre]

In general, I'd have appreciated a less demanding tone.

You'll find that all the WORKSPACE context can be found in index.md which is committed to the repo. The intent was to have users navigate to a site that would properly show the intended landing page as github renders README.md over index.md and I didn't want to break existing links. I think the use of https://docs.aspect.dev/ solved for usability and readability quite nicely without sacrificing SEO.

I will restore the committed docs but in the future, I will be less responsive to changes that are demanded vs requested. It's a fair argument that https://docs.aspect.dev/ is a 3rd party site and a competitor to https://flare.build/ (it'd seem) and it'd be unfair to rely on one vs another.

[zachgrayio]

👍 I could have phrased the issue title a little better for sure, was trying to convey only urgency

thanks for your responsiveness and the great work on the project