Question

What is the best platform for professional looking customer documentation?

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!

Mentioned
#Confluence #Documents #Knowledge Base #Design #Notion #Help Scout #Desk #GitBook #folk #around #Airtable #Front #Air #Zendesk #Intercom
Share
tekacs's avatar
2 months ago

For SDK documentation specifically, I would recommend a solution like Readme (https://readme.com/) or GitBook (either https://legacy.gitbook.com or https://gitbook.com depending on which you prefer).

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.

Great examples of documentation are:
- Front (using Readme): https://dev.frontapp.com/reference/introduction
- Airtable (custom, but similar to Readme?): - Airtable: https://airtable.com/api

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). :)

5 points
AnujAdhiya's avatar
2 months ago

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.

4 points
maguay's avatar
@maguay (replying to @AnujAdhiya )
2 months ago

Notion for documentation is a neat idea; would definitely make it easier to maintain documentation.

3 points
SethSamowitz's avatar
@SethSamowitz (replying to @AnujAdhiya )
2 months ago

We are looking at DeveloperHub

1 point
AnujAdhiya's avatar
@AnujAdhiya (replying to @SethSamowitz )
2 months ago

Looks nice!

1 point
patrickt010's avatar
2 months ago

We use v2.docusaurus.io at Iteratively, you can check it out at iterative.ly/docs so far I'm very happy with.

3 points
maguay's avatar
@maguay (replying to @patrickt010 )
2 months ago

Like how the Next sections look on the bottom of the page; pushes readers to actually go through all the documentation.

The code samples with multiple code options (in your CLI page, say, with the Brew and NPM sections) look nice. Are those easy to manage internally?

2 points
patrickt010's avatar
@patrickt010 (replying to @maguay )
2 months ago

Really simple, uses MDX so it's just components at the end of the day.

https://share.getcloudapp.com/7KumvK85

2 points
Dowi's avatar
@Dowi (replying to @patrickt010 )
11h

Hi, your docs looks great! How did you integrate Intercom to docusaurus? @patrickt010

1 point
patrickt010's avatar
@patrickt010 (replying to @Dowi )
1h

Using scripts as part of config.js. I created a separate file that loads the Intercom script.

1 point
optemization's avatar
2 months ago

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:

  1. Blende: https://www.notion.so/332426778b204a4db123030ca89ac13a
  2. Smartbnb: https://www.notion.so/smartbnb/Smartbnb-Help-Center-d328e1a72310473c9b196c84201aeeb1
  3. Notion: https://www.notion.so/Help-Support-e040febf70a94950b8620e6f00005004

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/).

3 points
maguay's avatar
@maguay (replying to @optemization )
2 months ago

Woah that's incredible your whole site is built on Notion. What led you to do that versus using a standard CMS—and do you see any downsides so far in using Notion to power your site?

Now imagine custom theming in Notion... that'd make it even better for this type of stuff!

3 points
barrald's avatar
2 months ago

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!)

2 points
maguay's avatar
2 months ago

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.

1 point
MikeRaia's avatar
2 months ago

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. :)

1 point
maguay's avatar
@maguay (replying to @MikeRaia )
2 months ago

Interesting, what got your team to pick Zendesk for documentation without using their email ticketing tools? And curious, what is your team using to manage support tickets?

1 point
MikeRaia's avatar
@MikeRaia (replying to @maguay )
2 months ago

We use our own software for support tickets. There was a thought we might switch to Zendesk ticketing at some point but we keep deciding against it collectively.

2 points
maguay's avatar
@maguay (replying to @MikeRaia )
2 months ago

Interesting! I'd have thought the support ticket side would be the more difficult one to build+maintain in-house.

1 point
volkanhaslak's avatar
2 months ago

Notion is a great choice! You can mold Notion any way you want to build the documents, tools and systems you need.

1 point
maguay's avatar
@maguay (replying to @volkanhaslak )
2 months ago

Interesting; you and @AnujAdhiya both recommended Notion for documentation. Had you used other documentation tools before and found Notion simpler, or were you already using Notion and just decided to extend its use into documentation?

1 point
The community for power users.