![]() ![]() Had we stuck with Gitbook, and written the API documentation there, we probably would’ve spent a week doing that, and done it poorly. This is excellent proof of why you need to pick the right tool for the job. We haven’t gotten to that last part yet, but we will. And Readme can even lift that further through integrations and prefilling auth keys. Still, in the end, we much rather have the API spec integrated within the documentation. We would’ve spent a lot of time documenting the API and considered using Postman as a solution to host our API spec. Who are we to ignore that fantastic fact. Then Readme swooped in and handed us an OpenAPI-2-Documentation solution. Writing your own reference tables, examples and guides with a clear overview is not something you whip up in an instance. We were about to roll out a new API, which we have just released, and API documentation is a tricky thing to do right. And considering they’re both Markdown-based, it should be pretty easy to switch too. So before you make up your mind on my article, make sure to check out both of them! They both have excellent free tiers, so there’s absolutely no reason to not try them both before committing. It could be our taste is just different, but to us, one thing we kept repeating while setting up Readme “Man, Readme looks nice”.ĭon’t get me wrong, Gitbook is still an excellent solution, and I’d still recommend it. And while, for both Readme and Gitbook, all documentation sites hosted by them look similar, there’s a vast difference in style. Not that dated matters much, but overall the feel was just not what we’re looking for. Gitbook is quite simplistic and not very inspiring, and it feels slightly dated in that regard as well. These kinds of delays eventually add up to slight annoyance when you’re trying to edit a few pages.Īnother downside, which is very much an opinion, was the design. It didn’t immediately open the edit screen, but it loaded to create a new branch in the background before actually showing the screen, which made working relatively slow. Even clicking the edit button in the Gitbook interface was slow. Gitbook was slow in loading, not just in the backend, also for our users. Though, for us, the benefits ended about here. The design of a hosted Gitbook solution is also quite simple, but clear for the users. Even submitting PRs on Github works well with Gitbook. It’s a great extension of having documentation hosted on Github it uses branches under the hood, allows for collaboration, and is very open-source-minded (despite their tool no longer being open-source). Gitbook was our tool of choice until just recently. Both have benefits and downsides, but there’s a clear winner for us. I’ve mentioned two of those solutions already Gitbook and Readme, and both of these we’re going to discuss here. ![]() And there are several players on the field. These platforms are great for rolling out documentation quickly, having hosting and updates managed for us, and having a worry-free situation regarding management. On the other hand are the hosted platforms, like Gitbook and Readme. Considering we’re just a small company, we cannot afford to spend hours maintaining, or even building, a website that can be made almost maintenance-free with low effort. However, with self-hosting comes extra maintenance, custom functionalities you need to write, styling and/or designing you need to do, and more. Using a self-hosted, open-source solution would make a lot of sense, being an open-source company ourselves. On one hand of the spectrum are the self-hosted solutions, from Vuepress to Docsify, and many others. Try writing the same text with markdown, or with a rich text editor, which works best for you? Yes, writing the exact same documentation in one tool can take much more time than in another. Not just how things look, but what functionalities you’re getting access to, the pricing, the maintenance, and the effort it takes to write. There are so many aspects to keep in mind. Not just because writing for a general audience isn’t easy, but also because finding the right solution for your (public) documentation can be a real challenge. ![]()
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |