Landing Page Feedback June 1, 2020

Generate Stripe-like API Documentation

kyle

Hi IH,

I’d love some feedback on Bulletin.io, a way to generate beautiful API documentation from your OpenAPI/Swagger file. On the site, you’ll see examples generated for some companies you should be familiar with - Slack, Zoom, and Spotify.

I’ve always admired Stripe’s documentation and thought it should be possible to get your API docs on a similar quality level. Through my research of different solutions, I just didn’t see anything that focused on the design of the docs, and Bulletin was born!

I realize the docs aren’t quite at the level of Stripe’s (yet) and there are some important areas still missing (e.g. request examples), but hopefully this gives you an idea of where the product is going.

Aiming to do a full launch in ~2 months. If you're interested, put your email in the email capture or shoot me an email - kyle at bulletin [dot] io

  1. 4

    FULL video feedback @ https://youtu.be/3vQ8Auax7HE

    • H2 color is too dark
    • Use your H2 words very carefully
    • I would move the screenshot of your tool higher up above the fold
    • Be careful with the naming conventions (I dont think Swagger is used any longer, it's OpenAPI since 2017!!!
    • Make sure that if you say you're selling beautiful API documentation
    • Don't use the whitespace where you don't need
    • Missing features deep-drill!!
    • Missing pricing
    • Missing testimonials from early users/friends/people you've discussed this with
    • I really love the PREVIEW buttons at the top, but you're also sending people to another page so you might lose their interest at this point ...too early on!
    • Give people an incentive to sign-up to your email list.
    1. 1

      Thanks so much for this feedback! This is all great and I agree with most/will be incorporating!

      1. 1

        You're welcome - out of curiosity did you consider or have subscribed to the channel? If yes why? If not why? I am trying to figure out if NOT asking people to sub during the video makes them wanna subscribe automatically just because the content is so good...or the opposite - then I need to improve the content!

        Don't go and subscribe now, I am not asking you to - rather trying to understand if you did/didn't and the reasons why

        1. 1

          Subscribed to the YouTube channel? I wouldn't say it's something consciously didn't do - I just never subscribe to any YouTube channels to be honest.

          I think if you had an email capture with a benefit of receiving periodic emails for optimizing landing pages, I would have opted in. Especially after you took the time to do the review here.

          1. 1

            Great feedback! Will definitely incorporate something sweet in the upcoming ones!

  2. 1

    I really like it, but the more I think about it, I want this to be a static site generator I control, not something I outsource to be hosted by a third party.

    The benefit I guess of a hosted solution, is that I would ideally want to put a bunch of information in my documentation in addition to what's in my Swagger definition. Something that would be better handled by a CMS that added things into the site while it was being generated. I guess a CMS would be better than just a bunch of markdown files somewhere it a build directory, because I would ideally have non-developers (or at least different sorts of developers) do the work that took my automatically-generated API docs and made them amazing.

    1. 1

      Thanks for this and I do agree/have faced the same issues. I think it needs to be a combination of both - generation from a swagger + markdown CMS. I found your swagger definition gets you about 60% of the way there, then there's manual additions that have to happen to get the polish needed to be publicly available.

      I'm planning on working in the ability to add custom content on top of what gets generated in order to solve this problem. This would allow a non-developer to add content in an interface.

      1. 1

        Yeah, I don't think the thing I'm looking for exists yet, but I've worked at startups that used things like Readme.io long-term (all user-generated) and companies that used something like doc-comments or Swagger. If you want to get to Stripe's level you probably need a mix of both, and a bunch of people-hours focused on improving documentation.

        We're pretty far behind and working with jsdoc comments vs. swagger right now.

        Interesting though, I have a feeling your target customer aspires to be "like Stripe", but is more like us -- lazy, and unmotivated to invest the resources to make their documentation a product. Maybe you don't want to focus as much on building the ideal CMS for building the perfect docs, and just focus on getting your customer to "Oh wow, my documentation site is actually pretty good!" as quickly as possible.

  3. 1

    This seems quite similar to Slate

    1. 1

      Indeed similar to Slate, but differs in a couple of areas:

      • It's a hosted solution - With Slate, you have to maintain yourself/it's open source.
      • It can be built off an OpenAPI/Swagger definition - Slate is build off markdown. This means there has to be a transformation layer you maintain OR someone how to hand craft all your APIs in Slate (error-prone)
      • Roadmap - Eventually, Bulletin will provide more than just API documentation. It's the initial starting point, but it will grow to more than a point solution (e.g. guides, knowledge base, releases, etc.)
      1. 2

        I think self-hosted is a HUGE added benefit, I would promote that feature on the website's homepage

  4. 1

    Wow! Amazing idea. I've always admired Stripe's API docs too! I've added my email, looking forward to the launch!

    1. 1

      Thanks!

  5. 1

    This comment was deleted a month ago.