Use gitbook editor on github7/3/2023 They are controlled through branches on your integrated GitHub repository and overall, that feature works well… If your soon-to-be-deprecated version of your documentation isn’t still being changed a couple of times a week. GitBook offers a Release feature to manage different versions of the documentation. ![]() Thus, contributions from those who don’t have access to the GitBook interface are limited to more simple tasks. My experience with GitBook indicates that it’s overly complicated (and a bit risky, even) to edit pages and the overall structure of the documentation through GitHub. While GitBook doesn’t let users add their own shortcodes, I believe the options they offer are sufficient for many of them: warnings, tips, notes, success messages, API requests, code blocks. It’s just a matter of creating a small HTML file, maybe adding a few lines to your CSS… And it’s pretty easy to reuse them in other projects. ShortcodesĪs a Hugo user, I really love shortcodes – they are a fantastic way of adding new functionalities (in special, visual or structural representation of some forms of content) without much work. You are able to keep multiple drafts at the same time, and that can be a particularly interesting feature for organizations that have multiple people editing multiple pages at the same time. I know a few people who used it for more simple tasks such as publishing a book translated into Brazilian Portuguese and those are fantastic use cases. I have to give credit where it’s due, GitBook really offers an accessible solution for documentation. What does it do well? Uncomplicated set up Worst of all, since I can’t be sure about how it treats my changes (and how they will interact with the current version of the documentation), a lot of those errors occurred in production (but were reverted as quickly as I created them, many of my modifications would break or remove a considerable amount of important pages). My knowledge about GitBook comes from their (somewhat brief) documentation and weeks of trial and error. Open Collective has been using it for a while, but its limitations started to disturb the documentation process as soon as I started pushing boundaries a bit in tasks like introducing a new organization of pages and groups of pages, or moving files to other folders. ![]() Is GitBook the right tool for your organization? – Īs I mentioned in my last post, GitBook, once a popular CLI tool used by many projects and organizations such as Django Girls, became a closed source platform that offers free and paid plans to both individuals and teams to manage and publish documentation.
0 Comments
Leave a Reply. |