My company is looking to switch platforms for our customer-facing documentation of our SDK. We currently use a mix of Confluence and isolated PDF's, but we are looking for something a little more professional.
Looking forward to everyone's recommendations!
Notion is a wonderful tool, but for SDK documentation it can prove to be fairly unstructured and harder to navigate.
Not only does it help you to be more consistent in your own work, but these tools have a lot of utilities built in to help a developer quickly jump to the relevant section of your documentation.
The most striking examples of documentation include usage examples, with real examples of calls/responses (for an API that might be data, but for an SDK you can still provide exemplar material). :)
We'd planned to just use Notion to do that at some point since you can control privacy on a page by page basis.
This helps with tool fatigue and you can get these pages looking pretty nice with the flexibility of these pages.
Notion (https://notion.so) all the way.
I discovered it two years and absolutely love it. Not the just the product but the team, culture and community — I'm a Notion Pro and consultant :)
I have not yet written a customer-facing wiki but a lot of companies do that. End users will appreciate the beautiful design and hyper fast search while you'll enjoy building and deploying it fast. Here are three examples:
As you'll notice only the Notion one is hosted on a custom domain. Even though the product does not have any tools for publishing, there is a fantastic and enthusiastic community around the product. Some folks built https://super.so that lets you host Notion pages on a custom domain, so that problem is solvable.
My consulting website, https://optemization.com is built entirely on Notion.
On the other hand, three significant drawbacks for you might be the lack of API, poor offline mode and slow page loading. The Notion team is working very hard on these features and I'd expect them to roll out by the end of 2020 ( not that helpful, I know).
If those drawbacks are critical to you, I'd suggest checking out Gitbook (https://www.gitbook.com/).
I looked at GitBook, Readme, and Docusaurus.
Wound up going with Gitbook to start. Reasonably priced (and they let us take less seats for the Team tier), fully-hosted, and easy to use.
That said, I expect we will transition to Docusaurus eventually, when we want to start self-hosting and do more custom styling. It's just way more flexible (and free!)
For standard software documentation, I’d typically recommend using a documentation tool built into your customer support app—for example, the help docs built into Help Scout, if you already used Help Scout to answer customer emails. The benefit there is that you can reuse docs in support emails to quickly answer questions.
That’s not as good of a solution for API/SDK/code-focused documentation where you might need to show sample code alongside the docs. For that, this discussion about platforms for customized API documentation would be worth checking too.
We're currently using ZenDesk, which is an OK solution, but for the cost and the fact that we don't use it for any of their support ticketing features we're on the lookout for something else. We've discussed building something on our current Web site CMS but if there's a good solution out there that's affordable we'd consider it. I'll be following this discussion closely. :)
My company is looking to switch platforms for our customer-facing documentation of our SDK. We currently use a mix of Confluence and isolated PDF's, but we are looking for something a little more p...
I have signed up for Roam Research (ages ago, no waiting list at the time), but I didn't like the fact that it was online only. Recently, I downloaded Obsidian (Obsidian.md), and I think Obsidian i...
Email apps come and go so fast—which one has kept you using it the longest, and why?