Documentation screencast boundaries

[stephendolan]

Hey all!

I'm currently focusing some energy on the community side of Lucky (tooling, documentation, onboarding, and learning) through things like LuckyCasts and LuckyDiff.com.

I'm attempting to keep my screencast content and the website guides somewhat in sync, and was looking for community (and core team) input on where a reasonable boundary is for letting folks add links to content that's not directly managed by the Lucky team.

We've already got a PR in flight to add something like a "Learn" section with a page devoted to screencasts. Determining what goes in that "Learn" section can be somewhat independent of this discussion, though it's definitely related.

However, take this issue as an example: luckyframework/website#396

Is it desirable for this PR to include a link/embed for the screencast within the main Lucky documentation content? That would probably be helpful, but here are some issues I could see arising:

• We become arbiters of good content ("Why is the LuckyCasts video good enough, but mine isn't?") and inadvertently discourage community members from contributing, which would be very opposite to the incredible community values that we currently have.
• In an effort to be inclusive and welcoming, we allow poor quality content into the guides that may reflect poorly for users who are judging whether or not they will choose Lucky based on learning materials available.
• Content previously posted gets put behind a paywall. I have no plans to do this, but let's say I open 20 PRs with 20 LuckyCasts embedded in the documentation. They're accepted, but a year from now, I update all of those videos to be "Previews" and require folks to pay for a LuckyCast subscription for content that at one point was free.
• Screencast content falls out of date with a significant update. This could be avoided by tagging videos with Lucky versions, but the core problem remains that while updating text is relatively easy both to review (I can search key terms) and update, updating a screencast is more complicated and could mean quite a bit of maintenance work on releases to peruse all of the linked screencasts for accuracy.

I'm playing devil's advocate to some extent since, as the creator of these screencasts, I'd love to see them included. However, having seen the two extremes with LaraCasts(owned and maintained by the creator of Laravel) and RailsCasts/GoRails (owned and maintained by third parties, with no official Rails guide references), I think it's worthwhile to at least consider the trade-offs we'd be making before we're in too deep!

[jwoertink]

There was a few of us that sort of had this grand "Learn section" idea all around the same time. For my idea, what I wanted to see was more of a page solely dedicated to community outreach/contributions. In this section, we wouldn't link to luckycasts.com/method-overrides.... But more just the home page a la "Awesome-Whatevers" type pages. So like my dev.to articles wouldn't be linked to, but we could link to the global dev search that includes the lucky tags. So in the case of someone else doing screen casts, if they had a page dedicated to a list of them like maybe a youtube channel, then we'd link to that.

[jwoertink]

I'm on the fence with that. On the one hand, it would be baller if you're scrolling through the guides and then bam there's a little tooltip or something that's like "Learn more on LuckyCasts!". Then again.... since that site is all you, and I know how time consuming it is, it would be easy for those to get out of sync, or you just get burned out and I'd hate for you to be burned out from a feeling of duty to keep our docs up to date that way. So I'm not "opposed" to the idea, but more hesitant on it.

Now, linking in a community section becomes easier since if any site goes dark, we can easily do a quick commit to remove that one link or whatever... I'd be curious to see what @edwardloveall thinks on this one. 🤔

[edwardloveall]

I'm pretty much exactly in the same boat as @jwoertink. If there's a page with links, that's a safe, single point of failure that the Lucky core team (even if that core team changes over time) can moderate. If content owned by someone else is used liberally throughout the guides, that's much riskier. The fact that we're a small team with other full-time jobs and limited time definitely has me lean more towards safe.

I'd love to have a great community content page where we can link to your and other's content though!

[stephendolan]

Agreed, you both raise great points! I'm sure @paulcsmith has an opinion on the matter too, but with the three of us on the same page we at least have a discussion to reference if we need to correct/revise PRs in the future that include external content in the main guide documentation.

[paulcsmith]

I think I'd like to take a differnt approach and have a separate website built with React and hosted with Kubernetes on a server I have in the closet :P

Kidding! I think I agree. I'd like to keep links out of the guides themselves (at least for now) but having some kind of "comunity" page with links would be great. That way we're not biasing anything or picking some people over others.

My original grand plan was to have screencasts on Lucky itself that we could show in the guides, but I think that's a long way out so this would be a great middle ground (IMO)

[jwoertink]

🤣 I've got rack mounts, let's do this!

[stephendolan]

To summarize where we've landed (so far):

• If/when we have "Community" or "Learn" area in the guides, any and all externally-provided reference content can go there and be discussed on a one-off basis in PRs for acceptance/rejection
• For all content within specific guide sections outside of the "Community" or "Learn" area, we'll aim to restrict that content to only markdown text and media (images, gifs, videos) that reside on the webserver. There will always be some edge cases (linking to a Postgres bug or guide that we know isn't going anywhere in the DB guides, for example), but those should be pretty obvious.

[paulcsmith]

That sounds like a great summary 👍