3 ms·
I wish Dan (the OP) had gone into more detail on exactly what techniques one can use to tell a story, because this is exactly what he does - very well! - as one
by btown 8y ago
I wish Dan (the OP) had gone into more detail on exactly what techniques one can use to tell a story, because this is exactly what he does - very well! - as one of the most prolific voices in the React (and perhaps all of frontend) community.
My personal take:
(1) Marketing shouldn't be an afterthought; it must be considered in the same way one would write code. Take a page from the folks who designed a custom website and icon for Heartbleed. To put it another way, think of "things that would distract someone from the main message" as "bugs" in your code. Certainly, some bugs need to be triaged before any launch. But they should all be triaged with open eyes and respect for the user experience.
(2) Don't assume people know acronyms or even the basics of your niche. Talk about potential use cases. Walk someone through the naive way of doing things, a less naive way of doing things, and why your thing naturally evolves/iterates on those. Make separate "background" pages if you want. Then take all of that as you would an essay you're writing for a class, and reshape it - find a thesis statement, tie everything back to it. Your launch post/README is a persuasive essay on why your thing is good. Even the "getting started" details are part of that persuasion - if it's easy to use, that's part of what makes it good.
Well-written technical documentation can be a joy when you are immersed in the excitement of the person who built it. And with any immersive experience, there are things that can take you out of it. Immerse people quickly and keep them there, and maybe, just maybe, they'll be curious enough to do background research on their own and engage with you on the merits of the project with context :)
- sandinmyjoints 8y ago> To put it another way, think of "things that would distract someone from the main message" as "bugs" in your code. This is the PR/communications industry. Once I understood this, and that a main message is one sentence at most -- a short phrase is even better -- interviews of people in politics made a lot more sense!
- btown 8y agoYep, the same way we write code and think “what are the implications of this function were called from a weird context,” so too do PR/communications folks “engineer” statements.