Vuejs.org: Cookbook blog recipe is undisclosed advertisement for author's business

[paultopia]

Hi there,

I love the new cookbook, but the blog recipe is a bit concerning. On reading that recipe, it is almost entirely focused on using a single, paid service, https://buttercms.com . It does not, however, disclose that this is a paid service. (To be fair, the pricing page does mention that you can ask for a free account for a personal website by contacting support.)

While the recipe does mention an alternative option (Nuxtent), it feels rather tacked on and doesn't give readers a real sense of the tradeoffs---it's also not a genuine alternative, since it seems like Nuxtent requires (I think?) using Nuxt, rather than working in any Vue site.

Here's the kicker: the author of the recipe is also the CEO of the paid service it recommends. This is also not disclosed anywhere in the recipe.

I don't want to accuse anyone of anything, but this seems... ethically problematic.

At a minimum, the fact that the recipe author is recommending his own paid service ought to be clearly disclosed right up front. And this might be a good opportunity for the maintainers to consider adding something to the code of conduct or otherwise adopting explicit ethical guidelines surrounding this kind of advertising behavior in the documentation.

[sdras]

Hey,
Thanks for stopping by. We didn't really mind this recipe being for a service like this because it was easy-to-read and well documented enough, and there are a number of paid-for services that we'd still accept recipes for (imagine a post about connecting to an AWS service, for example, even if there are open source alternatives). Recipes should also be specific enough that they're reproducible, thus requiring one to choose a service to demonstrate this kind of implementation.

That said, I do see what you're saying here and it brings up an interesting edge-case. We're talking internally about how to define our strategy for use cases like this, I'll get back to you shortly on what we decide. :) Thanks for looking out!

[paultopia]

Thanks for looking into this!

If I might be so bold as to make a suggestion in terms of policy---the key issue isn't the paid service so much as the conflict of interest---if people writing documentation are allowed to promote services that they make money from without disclosing that fact, it can reduce the quality of the documentation as well as the trust that end-users place in it. A secondary consideration is of fairness to the community at large including the maintainers and the project---if anyone is making a profit off the documentation, it probably ought to be the core maintainers, or those profits ought to be at least partly devoted to improving Vue.

So I think the problem could be mitigated by adopting an explicit conflict of interest policy requiring disclosure and, perhaps, more careful review to make sure that people with a financial stake in parts of documentation are truly giving advice unaffected by their financial interest.

[sdras]

We still think that's too hard a line to draw. We wouldn't want to deter even contributions for people who work for software that's paid for because they are probably at an expert level of understanding the integration, and could know more- in terms of release, limitations, and features, that might be useful. We're sorting it out internally and will get back to you soon

[autumnwoodberry]

I'm sure we will see plenty of line blurring in the future but on this issue I think the line is pretty clear. This is marketing, it doesn't conform to the goals of the cookbook, and the code samples have obvious errors.

• The recipe is copied verbatim from the documentation of a 3rd party service. It even reads like an advertisement:

  integrate our content API into your Vue.js app.

  That kind of wording doesn't belong in the vuejs.org official recipes in my opinion.

• The Cookbook gives developers examples to work off of that both cover common or interesting use cases, and also progressively explain more complex detail. Our goal is to move beyond a simple introductory example, and demonstrate concepts that are more widely applicable, as well as some caveats to the approach.

  Adding a blog to a vue application is not a common problem or an interesting one and the example code in this recipe does not demonstrate anything that isn't discussed at length in the documentation for vue and vue-router.

• This blog recipe does at least give us the opportunity to discuss this little gem:

  [Vue warn]: Error in render: "TypeError: Cannot read property 'title' of undefined"

  I don't think anyone is confused about how blogs work. Attempting to access non-existing properties on the other hand...

Seriously though, I think the broader issues being discussed here are very important. I don't want to see a cookbook filled with service integration guides. A recipe about how to architect and implement a service integration for your own backend API? That would be awesome.

[sdras]

Hi all,
Since there is a lot of interest in this issue, I gather that an update would be appreciated even though we haven’t reached a formal consensus yet. It’s been a couple of days and we’re all pretty busy over here, but we’ll be able to get back to you sometime next week.

We are considering taking down the post but I’m sure you’ll all understand when we say we have to tread lightly because we don’t want to discourage higher quality posts in the future. In a way, this recipe has given us an opportunity to create clearer-defined rules about what is acceptable. That’s great!

What we’ve heard is that people are concerned that these recipes might veer into marketing. We’re taking that seriously and writing up some rules that might help distinguish what constitutes between helpful and advertisement for the future. We have some plans for how this might be addressed that need a little polish before we can take action and share them.

Thank you for your patience! We want to make sure we head in the right direction for the future so that we can keep The Cookbook useful and open.

[jakelumetta]

@paultopia Author here. Thanks for the feedback 👍 This is definitely new territory for us so no harm intended. I think you raise some good points. Here's my thoughts, but I defer to @sdras on all of this.

• I'm happy to amend the article to disclose my role with ButterCMS (wasn't an intentional omission).
• ButterCMS is a free service for developers looking to experiment for personal use.
• What alternatives, other than Nuxtent, do you suggest for adding a blog to Vue.js?

[hitautodestruct]

@jakelumetta Regarding your last point:

What alternatives, other than Nuxtent, do you suggest for adding a blog to Vue.js?

You could use vue with the wordpress rest api. This would of course require you to setup a wordpress account but it's another free way to setup a blog using Vue.js

[jakelumetta]

@hitautodestruct Thanks Yotam, good suggestion. @sdras shall I make a revision to cover some of of the feedback?

[sdras]

Thanks everyone for your interest in this issue and your patience. We've talked it over and here is how we've decided to address this issue and issues of this nature in the future.

• Whenever we create an integration guide that's a paid service, we'll begin the recipe with a _small callout_ that lets the reader know this upfront. I will update the contributions guide with this detail, and make a new callout style for this purpose.
• Whenever possible, we'll try to also supply a recipe that's a free alternative. There is a large caveat here because we're all busy, so it might not be immediate.
• For this recipe in particular, we'll be making a few updates. I agree that including the Wordpress API would be great, as that's probably the most common use case. As mentioned earlier, there are a few updates to the text that I can work with @jakelumetta on to get it in better shape.
• Our official stance is that we're happy to receive integration guides, there are a number of integrations that are helpful to Vue developers, and we're all building different applications with different needs.

Thanks everyone! I think this conversation helps the Vue cookbook be a richer resource for the community.