This came up when talking to someone recently and figured I should share it with everyone. The topic is how to make communication for a product or a project really work, even if you’re just starting out.
Define a problem
Rather than using the usual tagline space in a webpage to say something in short choppy sentences, define what problem you are trying to solve. Make sure it’s a problem the reader has. Sometimes they may not be fully aware of how much of a problem this is.
Defining a problem is better than saying you are, for example, “the one stop-shop for all your data warehouse needs”, because well, that can mean too many things. If the reader can’t figure you out while reading your home page for 30 seconds, they are not going to send you an email, they are going to move on.
Show how you solve it
Explain how you solve the problem. Ideally this should include some architecture diagrams for people who learn better from seeing what a system is, than trying to infer it from explanations.
Once again, avoid the desire to speak in sentence fragments. Be honest and helpful. Your goal is to explain. If the customer decides they don’t need your product while looking at your web page, that’s fine. If the customer can’t understand what you do and can’t understand how that might help someone else they know (even if it doesn’t help them), that’s what you are trying to avoid.
Show how you’re different
People understand things better in context, so one of those comparison grids (but done nicely and fairly) that shows how you are different from other tools in the space may be helpful.
Be authentic and write the webpage with a goal of helping the user, not persuading. Show some things you do and show some things only your competitors do. Help them decide. If there are other tools that readers use with your tool, don’t just include a logo, but explain how they interact.
What you want to resist is an explanation that only makes sense if you already understand 5-6 products in the space though, because your readers may not understand those products. You also want to avoid pointing readers at other things they may want to like better, so be sure to identify the things that make you unique and valuable.
Include a clear link to the documentation
After you’ve explained all of the above, then include a link to the documentation. You don’t want the reader jumping off before they’ve read your introduction. If your whole project website *is* the documentation, all of the above is good content for the documentation homepage.
I don’t think you should link to GitHub prominently, as people may jump away and start reading your README and then get lost. You want to explain the basics and maybe show that at the bottom.
If you do have an open source project, your README should be well crafted and link to the website, tutorials, documentation, and contribution process. Resist the urge to explain how to install/use the product in your readme, as your online documentation is a form of a (project) marketing and is always going to be better installation guide because you can format it more nicely. Point to your better online resources instead.
If relevant, there should be a very clear repository with examples, and nothing but in-context examples, since that can help readers understand your product in a way that reference documentation and descriptive language cannot.
The examples should be something that help the user imagine themselves using your product - so ideally should be something that they would be doing in their day-to-day job, or else, just something fun and interesting that they may be curious about. This also applies to screenshots, don’t just use dummy data.
Install instructions are good, tutorials are good, examples are good. Reference documentation is good too, but you need those other things first. Be sure the content is written for everyone, not just hyper-technical potential super-fans, since you want to cast a wide net.
People enjoy learning new things, so be willing to re-explain some things you think some people might not know if it helps them understand your product better.
Encourage communications - a lot!
People will reach out with ideas if they feel welcome, so ask for feedback in your documentation and make that request prominent. Have a very clear contact us form on your web page as well.
Conversations were one of the major reason I built software, I liked interacting - and that made better products which generated more communications. It’s a very positive feedback loop!
If you think you don’t like the idea of marketing your project, think about it that way and your opinion may change pretty quickly! It’s all about helping people and engaging with people more.
This is all pretty simple, but a lot of products and projects don’t do this. Because we have a lot of bad web page examples out there, they are apt to get caught up in catch-phrases and sentence fragments and try to say as little as possible, hoping to keep the product sound very general-purpose, and seek to route customers to sign-up, buy, or talk to sales. The truth is the customer isn’t ready yet, you have to help them understand you first!
Anticipate their needs and explain what you do, make them interested, and answer the questions you think they have. That approach changes everything.