I am excited to see so many wonderful ATproto apps and tools being developed! I would love to be able to recommend some of these outside of Bluesky, but I can already anticipate the frustration and confusion by some of my work colleagues who lack time to try figuring things out on their own, or even to ask for help....and I lack the time to help with on-boarding these days.
Also, when trying to explain why my book publishing industry creators and colleagues should join Bluesky, in terms of keeping control over one's own id and content, not letting themselves get walled in by a single corporation etc....I find that while they do care, the bottom line for most is that they are trying to keep their businesses afloat and relevant, whether that biz is big or small, and they have bills to pay. Some tell me privately that while they dislike having to be part of (insert name of super-popular and well-funded platform or platforms here), that they need to go where their readers are. They're tired of some Bluesky types wagging their fingers and condemning. Tired of being made to feel guilty about still using (name condemned platform here), they end up just quietly leaving Bluesky to go where their readers are, or potential clients or agents or editors etc. For the record, whenever I encounter someone like this, I never make them feel guilty but instead focus on the positive reasons why Bluesky is worth checking out.
Many are short on time or lack the energy to figure out why ATproto is so important. They just want to figure out what they need to do in order to start up a blog or newsletter or feed etc.
Of course I sympathize, but I'm also a tad frustrated. Not with anyone in particular, but just because I truly do think ATproto is a much-needed breath of fresh air, that it could change so much for the good. I've poured many, many hours into tips and tutorials, and not insignificant funds from my own pocket in trying to lure more of the children's book community to Bluesky. Some stay, but many don't.
I have renewed hope with the new ATproto blogging apps as well as the upcoming Community Spaces on Bluesky, but part of me wonders if this will help at all if there is no easy on-boarding for non-techies.
Which brings me back to the importance of user documentation.
More about why non-techie documentation matters
Most users care less about the architecture behind your app and more about how to complete a particular task.
It makes it easier for those of us who like and use your app already to promote it to our non-techie friends and work colleagues.
Tips for writing good user documentation
Have an About page that isn't packed full of tech jargon. Have a mission statement or a clear, succinct paragraph that IMMEDIATELY conveys the heart of your app or tool to non-techie users and WHY they should sign up.
Know your audience. Are you writing for developers? The app's internal team? Or for the end user?
Use clear, plain language. Avoid acronyms or tech jargon unless you provide a short definition at the beginning.
Use headings. Don't just have a wall of text. Break your content down into sections with appropriate headings. This makes it easier to skim and easier to read. Users can skip to the bits they are most interested in.
Resist the urge to explain how things work under the hood unless this is essential for your end user to start using your app/tool. Start with the basics, start with the simple concepts. You can always give your end user the option to find out more with an Advanced Topics or similar section at the end or on another page.
"Feature-led documentation often opens with what something is. User-friendly documentation opens with what it helps them do." - Helpsite article
Keep your user documentation up-to-date. Users will get frustrated otherwise, and may decide your app is just not worth pursuing.
Include screenshots and images, clearly labelled. Having visual aids throughout your documentation will help break up the text, make it a more engaging experience for users, and help those who lean toward visual learning. However, remember alt text and don't JUST rely on images. Some users may have visual issues, or won't have the bandwidth to view your images. Users want visual confirmation that they're doing steps correctly, that they're in the right place.
Video examples also help, for those who find that the easiest way! Make videos short. On YouTube, you could have a playlist that includes all these bite-sized "lessons." You could embed these videos in your written documentation.
Include examples that are task-focused. If you are an ATproto blogging platform, for example, you could show different ways of sharing a blog post and what others see when the post is shared. Or how to embed a link in a post. Or examples of Markdown one could use to format a post. etc etc
Have a special short/quick On-boarding tutorial for those who want to jump in right away but don't even know how to get started.
Have a way of users getting support if they need it. One advantage of having good user documentation is that (hopefully) most of the most frequently asked questions and issues will already be covered.
Also...
Make it super-easy for users to find your documentation, ideally from anywhere in your app.
And again...keep your documentation up-to-date, in sync with how your app looks and works.
Test your documentation with users who are NOT already familiar with your app.
Consider hiring an experienced technical writer.
QUESTION: Do you have any other tips or resources for writing good documentation for non-techies? Any examples you'd like to share?
I like BlueskyFeedCreator's user documentation. At the time, I knew of only BSFC and another feed creator. The latter was the most popular and did have a helpful community, but I opted for BSFC and even opted for a paid plan because of the user documentation and the responsiveness of the developer to answer my specific questions. I like that the main topics are all in different sections, that it has plenty of visual examples, is kept updated, and has a search field at the top. Latter is especially appreciated because BSFC now has so many features! This way I can quickly look for what I want to learn more about, or to refresh my memory about an older feature.
Some Helpful Resources
Ten tips for writing a user guide - by Marianne Crowder.
How to write documentation for non-technical users - on Helpsite.com
For more about me and my work, see https://debbieohi.com/
For more ATmosphere bloggy goodness, see https://debbieohi.com/links/