A new home for Open Collective's documentation #2595
I've been working with Open Collective's documentation platform of choice, GitBook, every day. GitBook, for those who aren't familiar with that name, used to be a popular open source CLI tool used by many open initiatives such as Django Girls, and is now a documentation platform.
Our main issue
GitBook is a great tool for projects with a fixed release development model as it offers many tools to separate old and new versions of the documentation, but using it can get tricky in a rolling release project. Making aggressive changes in the structure of the documentation often made multiple pages disappear with no explanation whatsoever, and GitBook's interface and documentation would offer us no explanation on why it kept happening.
Lastly, even though the GitBook team states that all features offered on the CLI tool were incorporated to the (now) proprietary platform, there are quite a few significant differences between them, including:
And while they have finally added native analytics support, they only offer integration with Google Analytics (and even that it's limited to general page views).
For a more detailed analysis of GitBook, refer to two of my blog posts on the matter:
I believe that a perfect documentation tool for Open Collective should fulfill the following requirements:
As a technical writer, I would recommend a new documentation tool. GitBook, as it stands now, cannot fulfill all of those requirements.
I made a small research on what other open source projects use and asked the fediverse what would they recommend to replace GitBook. Here are a few options focused on documentation:
There are ways to build documentation with frameworks and static site generators such as Hugo, but they weren't created specifically for documentation.
I want to hear from you
Hi ! Thanks for taking this up. So when it comes to Gitbook I think that is one of the best option which allow the docs in an organized way. But at the same time experiencing features that caused problems can be a great issue and gives a hint to move out of it.
@contraexemplo I understand where you're coming from, the frustrations with GitBook, and your list of requirements makes perfectly sense. I'm afraid however that we'll not find the perfect tool matching all these requirements. To get facts, would be great to start the research, compare the different alternatives in a table, see how they score compared to these requirements.
Regarding the implementation, the GitBook setup was initially tackled independently from the engineering team, which is great because we have very limited resources right now. If the documentation team decide on using a new tool, I should warn that we'll not have much time to help, because we need to focus on our set priorities.
So, from my point of view, I think it's great to research what tool could be better than GitBook. However I would not rush the implementation and would recommend to push GitBook to its limit, at least until the end of the year.
@znarf I agree with that! That's something Alanna and I discussed a bit last night during our own meeting. We solved most of the main issues in the last few days (redirecting old links to the right content, restructuring the whole documentation switching branches). This is something Open Collective should think about in the long-term, not necessarily something that should be solved at this very moment.
I worked with an organization that changed their documentation tools four times in two years — GitHub Wiki to DokuWiki to MediaWiki and then to Docsify. I wasn't their technical writer nor the person responsible for their tools, I was just an intern that tried to help them anytime I could. Every time it happened it was such a rushed process I could feel everyone getting more and more frustrated with each shortcoming they would find in every tool.
That's why I proposed this issue — with a bit more of experience with a few more tools and having another person's perspective in mind, you are able to paint a good picture of the current state of the documentation process and decide what should change and what should be kept. But that's something that should be done slowly, it should be a separate project even (which is what happened with MediaWiki in this round of Google Season of Docs — another technical writer used my work as an Outreachy intern to understand better the state of MediaWiki's documentation and to propose a related project).
Circling back here after a nice discussion with @contraexemplo and @alanna in Slack. I proposed the idea of putting together some contribution events where I reside in Portland, OR. Considering Read/Write the Docs is one of many OSS projects/communities with a substantial presence here, we could probably assemble a team to work on migration (or really any type of OSS project).
The following are the steps @alanna proposed upon hearing about this potential collaboration -
Considering @contraexemplo is wrapping up involvement with Google Season of Docs soon, continuing to make the case for switching to RTD could be a great next project.
If it turns out we can make a technical and business case (there are multiple ways these projects/communities could collaborate), @contraexemplo and other folks interested could collaborate with Open Collective and hundreds of other projects using the platform who need great documentation.