New home page and documentation site? Wishlist?

[gabek]

After hitting the 5yr anniversary milestone, I've been thinking about our current website a bit. It's been quite useful to us, and while there isn't anything "wrong", I think there are things we should absolutely look at improving.

I know this topic is something @germainelee has brought up in the past, but it wasn't the right time.

I wanted to open this discussion as a place for wishlist items and ideas. I had a high level chat with @gingervitis, and here's things I'd change about the site:

• The home page assumes you know what Owncast is and what it's for. Any of the attempts at sharing value props are vague. It doesn't say what problem it solves, and why this particular solution is a good one.
• The donors and contributors list of avatars is just too much. We need a better way of showing who supports and contributes without making the page feel overwhelming.
• We should show a current version and release date or something prominently, so somebody who drops by the page without knowing anything about the open-source project can see that it's actively being worked on and gets regular updates. This is very important to know when looking at pieces of software.
• We've come to the point with our documentation that I can't find things anymore. I'll try to find a document for somebody, and I know the information I need is somewhere, but I have no idea where, and have no idea how to find it. The amount of documentation is super helpful to people, but it's very difficult to find anything in. Breaking things into useful categories could make a difference. "Getting started" should be different than "Configuration". Right now, "Configuration" and "Guides" are confusing because some of the guides are just guides on how to configure things. It would also be good to break things into "Advanced" topics, and topics that don't have anything to do with Owncast, but are helpful to people (like how to setup systemd). We also mix troubleshooting documentation in there to make it more confusing.
• Our search is pretty useless, you can't even search for something you're looking for. The closest thing we have to useful search is the little chatbot that will route you to documentation. I will almost say our search doesn't work at all unless you already know the name of the document you're looking for.
• I want to be able to build React components on our website. There's been a handful of times I wanted to build something for our page, but having a way to bring in UI frameworks and the ability to build actual components would make that easier for me. For example, I've had an idea of a widget that helps you determine resources. You say you want 2 outputs, and you'll have x number of viewers, it'll give you an estimate of what kind of network traffic and CPU usage you might expect. You'd be able to change the numbers and watch in real time to get other estimates. I feel like people would like this, but it's not something I feel like I have the tools to build right now given our stack. Things like our roadmap also fall into this category. If we supported bringing in UI components we could probably improve upon our Quickstart and Troubleshooting wizards as well. Right now those are very difficult to work with if you want to add or change something.
• We have a cute Owncat now, it would be nice to add some levity and personality to the site by using that in places.
• We have a merch store now, maybe we should show that more prominently? Have a section on the home page showing that off? I don't want to be a sellout, but I also think having a cool thing like that can add more to people's impression of a project. "Wow, they even have all this merch, they seem cool".
• Show a way to subscribe to the newsletter?
• It would be cool to show the contributors to each doc page, since people who work on documentation don't usually get credit.

Positive things about the current site

• We have a lot of helpful documentation. We just need a better way of finding what you need.
• I think the Quickstart has been very useful in getting people up and running quickly.
• I, personally, think the Troubleshooting wizard is pretty good. Maybe the questions and routing could be improved upon, but the question/answer approach of solving people's problems I think is a good one.

I'd love to hear ideas from other people.

• What would you, personally, wish we had when you were first looking at Owncast?
• What would you, personally, wish we had after you started using Owncast?
• What do you think, generally, would be improvements to help people who drop by the site and want to discover what Owncast is? Not what you want.

[germainelee]

I agree with all the points you mentioned. The website is a critical entry point to convert visitors to users. Below are some of the things that could be improved:

• Revise footer

  • Any other relevant links to put?
  • make subscribe to newsletter more obvious? Add Newsletter link in footer of website #4310

• Add credits (below footer)

  • Website developed and designed by community. Link to a separate page of contributors?
  • If we decide to add mascot on homepage, add the credit "Owncast mascot created by {contributor}" in/below footer

• Display github Star count to show that people find this project valuable
  Show the star count on the website #4280

• Testimonials to establish social proof
  website: some Author URLs are "outdated" #4338

• contrast of blue and purple text against dark backgrounds

• overall look. I've seen many frontend developers' portfolios created on github with fancy animations and transitions. I'm not sure if that is possible here.

[germainelee]

Maybe a short video to show how fast it is to set up? But there are multiple ways... so I'm not sure if this is feasible

[gabek]

The very, very first version of the home page had that but I felt like it was too nerdy for that to be the first thing that you see, so it got moved to the actual installer page. https://owncast.online/quickstart/installer/

[Solomon-mithra]

@gabek as user I would like to see the cmd gif/video on how easy it is to setup in the homepage

[gabek]

And that's perfectly valid for somebody who already knows what Owncast has to offer, knows what they're looking for, and is at the stage of wondering what it takes to install it. But if you're the person wondering what Owncast is all about or browsing, then having shell commands being the first thing you see isn't going to answer any of the questions about how it helps you live stream, or even what it does at all.

[gabek]

I think that's really good to keep in mind, though. The web site has essentially two completely different audiences.

1. For one, it's a marketing site. It explains what Owncast is, tells people why it's useful, and convinces them it's a good solution to their problems.
2. For another audience it's a technical resource. It tells them how to install it, it helps them troubleshoot, it's an archive of detailed documentation for people who are already using the software or are in the process of getting it running.

These two audiences are completely different. And it's interesting when you see pages and you can tell what audience they're targeting.

I thought I'd go through some other projects and see what they're doing.

Look at https://www.11ty.dev/ for example. They're heavily targeting the technical side. They're not wasting any time explaining anything high level. They jump right into using it.

i18next, the translation framework https://www.i18next.com/, doesn't go technical at all. It talks about what it is, goes in depth about a lot of its features, but does have a video if you want to learn more.

The Go Programming Language https://go.dev/ focuses up front of explaining what Go is, and why you should use it. And as you scroll down it gets more technical.

Chart.js https://www.chartjs.org/ is interesting. Their home page is mostly just a changelog of their release updates. So they really assume you already know what it is.

Prettier https://prettier.io/, the source code formatter, doesn't go technical at all, and only talks about its features. It also shows off its merch store.

Jest https://jestjs.io/, the Javascript testing framework, focuses mostly on features, but has tiny screenshots of the software in use.

A middle ground is something like https://react.dev/. They show source code, but they also show the user-friendly side so non-technical people could look at it and understand it.

[Solomon-mithra]

I really love where this discussion is heading. I recently discovered Owncast and was immediately curious to get involved. That said, like @gabek mentioned, as a new user it wasn’t immediately clear what the project was about or what problems it aimed to solve.

Owncast clearly has a lot of value and potential—especially in this current era of creators—but it took me a bit of digging to realize that. That’s why I took the initiative to contribute a small improvement (UI improvements: Enhanced hero section and search functionality #205).

I believe visitors should be able to understand what Owncast is within the first few seconds of landing on the site. A modern, clean homepage that clearly communicates the value prop would go a long way—not just in user clarity, but also in subtly reflecting the professionalism and innovation behind the project.

So to answer your questions:

• When I first found Owncast, I wish the homepage had a clearer explanation and visual polish that made me immediately go “oh, this is cool and useful.”
• After starting to use Owncast, better navigation and easier discoverability in the docs would’ve helped me a lot.
• For new visitors, I think quick clarity and a fresh, modern design can really help Owncast stand out and communicate its value instantly.

Looking forward to contributing more!

[gabek]

I feel like talking about colors is so in the weeds. All the topics above are huge, high-level issues that need to be designed and discussed. The color of some text is far too premature. We don't need to tweak the home page, in order to fix all of those issues we need a new home page.

[gabek]

If it's helpful, when I think about "updating the home page" this is what I think about:

https://design.penpot.app/#/view?file-id=53ae55ce-c456-815d-8006-6f16774b7fc0&page-id=53ae55ce-c456-815d-8006-6f16774b7fc1&section=interactions&index=0&share-id=53ae55ce-c456-815d-8006-6f1c1dfe8637

1. Most important is what problems need to be solved with the home page
2. Decide what needs to be on the home page to solve those problems
3. Start experimenting with laying out ideas (not designs)
4. Iterate until all the goals are reached and all the problems that need to be solved are solved
5. Design the page
6. Iterate on the design

The design doesn't come until much later.

[Solomon-mithra]

The points you mentioned are indeed accurate. Here are some additional observations I made:

• The search box or suggestion box lacks scrollability, making it challenging to access the content when expanded on a laptop.

• The Hero section could effectively communicate the unique features and value proposition of the independent stream service.

• The contribution and donor options can be reduced to five circles, with the sixth circle displaying a range like “99+,” enhancing clarity and understanding.

• The live stream links could be presented in a carousel format, allowing users to quickly access the top 10 streams.

• Including a video from the QuickStart document showcasing the ease and speed of setup would serve as an effective selling or attracting point.

These are just a few observations I made. If necessary, I can create a Figma prototype in the future once the hierarchy of the sections is defined.

[germainelee]

What im saying is that there would be a heck load of discussions from defining the goals the website needs to meet all the way to the finest details, like colours in the UI design phase.

"Should the hero text be pink or white?" Is just an example to show the questions that would come up when fine tuning in later stages. Questions for defining-the-goal stage include "What do audience/visitors expect to find or do there?"

I understand that there are many steps and effort needed before implementation. Given its big scope, what is the best way to discuss the different topics async? Here? A document brief, like how I wrote stuff in Notion for Scheduling Livestream? A whiteboard tool (e.g, miro)? GitHub issues?

[gabek]

That's why I opened this discussion here. To simply collect thoughts on what people wished the web site accomplished better. Just starting with a data collecting exercise to determine what problems are there to solve. There's been some good points made already.

[gabek]

Another important thing we could improve on is be better about discussing all the different ways people can watch an Owncast-powered stream on other devices. Right now we have this very complicated, and super unhelpful document that I don't think anybody has ever read. https://owncast.online/docs/watching-on-tvs/

[gabek]

I would argue that the "streams live right now" on the home page is counterproductive and the next version of the page shouldn't have it. The entire page doesn't try to be like Twitch or a streaming platform or a social site at all, and then in one little part we're like "go check out these streams!" Just feels unprofessional, and the people looking at Owncast for non-social reasons might be confused by that. We should rely on the directory for sharing streams, not the home page.

That being said, maybe we should have a section on the home page that more prominently tries to mention the directory as an optional thing.

[germainelee]

Not sure if updating the website would have 'good first issue' tasks. if so, it would be great to "finalise" the content so that people participating in the hacktoberfest could pick those up.

[gabek]

It probably doesn't, at least not anytime soon, since we haven't started discussing anything. We've just been collecting ideas. Each idea will probably take months to discuss given how slow conversations move.

The last home page was built by a friend of mine, it's generally challenging to get people who really like working on UI to work on that stuff. So I imagine that will be the case here. I don't anticipate that people will want to contribute to a home page that isn't the Owncast software. So I'll just have to work on it slowly.

[Solomon-mithra]

Hey @gabek , I can work on the UI and the homepage. Once we have finalized on the wireframe or a design. If you require a Figma design I can work on that too.

[gabek]

Awesome, that's great news. I really appreciate that! Stay tuned to this thread as we continue to work things out.

[gabek]

Side note: I just learned that Owncast is on some block list due to "illegal downloads". My guess is it's because of the list of streams on our home page, or possibly the directory in general. So I just now removed the list of streams from the Owncast home page. So now it's for sure we can't have it on the next version of the site.

[germainelee]

how did you find out that Owncast is on some blocklist?

[gabek]

I tried to access it from an airport and it was blocked.

[germainelee]

That sucks as now we don't have Live proof, which may hurt credibility. was the directory embedded?

[germainelee]

I got AI to help prototype the site.

[gabek]

How did it know what what should go on the page and what it should look like when we don't even know that?

[germainelee]

I asked ChatGPT to analyse the existing website and propose content based on this discussion. Then I made slight changes from there using another AI. So i did very little coding.

[gabek]

Seems like a good way to visualize ideas!

[gabek]

We will want an updated screenshot, as the current one on the homepage is from the old Owncast UI, and is no longer representative of what it looks like: https://owncast.online/images/owncast-splash.png

[germainelee]

Should the tv ui be included?

[gabek]

Should the tv ui be included?

What do you mean by a TV UI?

[germainelee]

Iirc owncast could work with tvOS?

[gabek]

Oh I see what you mean. Owncast is just the server software. There are different ways to watch Owncast-powered streams, like that tvOS and Roku app, but we're not opinionated. We have a page that discusses different ways to watch streams, and that needs to be improved a lot.

[germainelee]

Remember to update the screenshot in the following places:

• Storybook
• website

[gabek]

I started putting down the thoughts shared here into a document to start planning. https://docs.owncast.dev/updated-web-site-2025

[gabek]

I started putting together an actual TODO list in the web site doc.

I've also made it so any changes to the new dev branch get auto-deployed to https://owncast-preview.surge.sh for testing.

[germainelee]

It would be cool to show the contributors to each doc page, since people who work on documentation don't usually get credit.

Totally agree! That is a form of intrinsic reward. When I first saw it in Ant Design Documentation, i had the feeling of wanting to contribute to it to see my avatar there. Can docusaurus do that?

[gabek]

It's not built-in, but there's a thread about how to pull it off: facebook/docusaurus#6218

So, yes!

[gabek]

I started a POC on a owncast-docusaurus branch just to see if I could get it to work. I was able to move all the documentation over and built a contributors component.

[germainelee]

NICE!

Some docs have this thumbs up/down button. But I don't think we need it. writing the idea down first.

Source: Github docs

Source: Posthog docs

[gabek]

This is a static site just like our current site, there's no server component to it, so we can't do any interactive server-side functionality like that unless it's through a 3rd party or we build something new from scratch.

If it helps at all, the little AI support chat that's on the page gets used, and literally nobody ever clicks the feedback. Personally, I've also never clicked the feedback buttons on any piece of documentation I've ever looked at.

[ArtistDev44]

Hello guys, just created a new discussion because I am interested for your website rebrand.

[gabek]

I took a first pass at reorganizing and renaming all the documentation to try to be more useful with the next version of the documentation page. Feedback welcome: https://owncast-preview.surge.sh/docs/

[gabek]

More changes to the docs have been made to try to organize them into the right places, and name them in a way that makes sense.

I've also started to experiment with things on the home page to start working towards getting that to somewhere.

[gabek]

And a work in progress home page continues to be iterated on at: https://owncast-preview.surge.sh/index-new/

[LiteralGrill]

This may be a minor thing, but I got raided by trolls tonight. Thankfully, y'all got cool moderation tools so I banned them!

Unfortunately, they made their usernames slurs, so when I banned them, their name with said slur was shown in a huge highlighted box in the chat which wasn't exactly great. It's a very small thing to ask a change for, but I'd love for that not to be a thing.

I also wouldn't mind a way to choose my own profanity filter, so I could cut things like slurs but still let folks swear within reason and such. Though it's not as top priority.

[gabek]

Hi there, this thread is for the new documentation site. Please search through previous issues and open a new issue if there's a feature request you'd like to discuss.

[gabek]

Since the new site is quite far along at this point, I'm collecting a list of tactical issues and remaining todos to complete: #4720

The goal is to release the site alongside Owncast v0.3.0.