A new home for Open Collective's documentation

[contraexemplo]

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:

• Use of a specific versioning system
• No internationalization support
• No offline documentation
• No native tool to export documentation

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:

• My first impressions of GitBook
• Is GitBook the right tool for your organization?

My insight

I believe that a perfect documentation tool for Open Collective should fulfill the following requirements:

• Use Markdown
• Be open source (to avoid the perils of vendor lock-in)
• Be well documented
• Blend well with Open Collective’s visual identity
• Be compliant with W3C’s accessibility standards
• Be simple to set up, manage and maintain
• Offer an easy process to create and edit pages for both core contributors and external ones
• Offer internationalization tools
• Have some degree of integration with a version control tool
• Have an integrated search tool or make it easy to integrate one
• Let us use any analytics solution

Negotiable features:

• Have a database
• Have an integrated editing interface

As a technical writer, I would recommend a new documentation tool. GitBook, as it stands now, cannot fulfill all of those requirements.

Options

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:

• Read the Docs, which supports both MkDocs and Sphinx (note: see pricing)
• mdBook, a re-implementation of GitBook created by the Rust team
• Docsify
• Docusaurus

There are ways to build documentation with frameworks and static site generators such as Hugo, but they weren't created specifically for documentation.

One of Florence's contributors kindly shared their report on documentation tools with us. It's a great read and a lot of their needs are similar to ours.

I want to hear from you

• Should we abadon GitBook?
• When it comes to documentation, what are your needs?
• What is your favorite option?
• What should we be careful about?

[alanna]

Thank you @contraexemplo ! I am following this discussion with interest.

I will bring it up with @piamancini @znarf and the rest of the team in our meeting today.

@jaskirat2000 do you have any thoughts?

[jaskiratsingh2000]

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.
I would prefer the "Read the docs" documentation set up because it has got mant well organized set of features which are way better than gitbook and even support markdown. But I see a high configuration cost for it.
If cost is not a problem we can definitely go for "Read the Docs"

Thanks

[alanna]

@znarf - did you want to add the comments here that you brought up in the meeting?

[znarf]

@alanna sure

@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.

[contraexemplo]

@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).

[znarf]

Just a small note, docsify and docusaurus are on Open Collective, so it's always a plus when picking a tool.

[gusaus]

Has anyone reached out to @ericholscher about seeing if https://readthedocs.org/ could provide a better option? Seems like there could be some opportunities to collaborate on tools and models to sustain https://readthedocs.org/sustainability/

[ericholscher]

Happy to chat -- of note, readthedocs.org for open source stuff is free, whereas readthedocs.com is paid for closed source. We love Open Collective, and would happily offer a discounted or free plan if y'all have specific need of private repos. 👍 🎉

[alanna]

Thank you @ericholscher ! We'd love to collaborate. We're not ready to make the jump right away due to lack of team capacity, but we'll certainly follow up in the future. As of now all our docs are totally open so we don't have a need for private repos.

[gusaus]

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 -

• make the case for switching to RTD on the github thread and get buy in
• scope out what the migration project would actually entail and run it by @françois Hodierne to clarify what dev resources would be required
• if he says it’s something an external contributor can handle with minimal support, then we can go for it
• if it turns out that it will require substantial support for the core team, we need to hold off until that capacity is available

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.

[contraexemplo]

@ericholscher We had an incident with our current documentation platform last week that left me curious about how RTD deals with downtime.

• Do you have an estimate of RTD uptime?
• Have you ever faced an incident that caused RTD to become unstable or unavailable for a few minutes or hours? How did RTD address that issue and communicated with all communities which rely on that service?

[Betree]

Bumping this, Gitbook broke the images on https://docs.opencollective.com/help/collectives/subcollectives for the second time and it's pretty frustrating.

[contraexemplo]

@Betree It's a really good thing you're sharing that because I noticed something like that recently and I was afraid it was my fault for not paying enough attention. 😬 I went through every page last month to check on every link and image and I had the impression that a few sections broke again weeks after I fixed them. 🤔