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 kommentar(er)
