Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

A new home for Open Collective's documentation #2595

Open
contraexemplo opened this issue Nov 4, 2019 · 41 comments
Open

A new home for Open Collective's documentation #2595

contraexemplo opened this issue Nov 4, 2019 · 41 comments

Comments

@contraexemplo
Copy link

@contraexemplo contraexemplo commented Nov 4, 2019

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 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:

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
Copy link
Contributor

@alanna alanna commented Nov 5, 2019

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
Copy link
Member

@jaskiratsingh2000 jaskiratsingh2000 commented Nov 5, 2019

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
Copy link
Contributor

@alanna alanna commented Nov 6, 2019

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

@znarf
Copy link
Member

@znarf znarf commented Nov 7, 2019

@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
Copy link
Author

@contraexemplo contraexemplo commented Nov 7, 2019

@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
Copy link
Member

@znarf znarf commented Nov 13, 2019

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

@gusaus
Copy link

@gusaus gusaus commented Nov 22, 2019

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
Copy link

@ericholscher ericholscher commented Nov 22, 2019

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
Copy link
Contributor

@alanna alanna commented Nov 22, 2019

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
Copy link

@gusaus gusaus commented Nov 23, 2019

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
Copy link
Author

@contraexemplo contraexemplo commented Dec 15, 2019

@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
Copy link
Member

@Betree Betree commented Feb 17, 2020

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

@contraexemplo
Copy link
Author

@contraexemplo contraexemplo commented Feb 17, 2020

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

@Betree
Copy link
Member

@Betree Betree commented Feb 17, 2020

Some of them are still broken like https://docs.opencollective.com/help/internal/moderation but I don't want to fix them now, I spent some time doing it too last week and don't want to loose more time if they haven't fixed it.

We should contact Gitbook to report this. Let me know if you want me to take care of it.

@contraexemplo
Copy link
Author

@contraexemplo contraexemplo commented Feb 17, 2020

@Betree Could you try sending them an email reporting this? I've sent them some emails a few times on bugs like this and some suggestions, but the only time I actually got a response was when GitBook had a long downtime last year. Also, should we open a new issue dedicated to this to track it or should we keep any discussions on that here?

@Betree
Copy link
Member

@Betree Betree commented Feb 17, 2020

Extracted the issue to #2917. I think we can send the text or a link to the issue directly to Gitbook.

@stale
Copy link

@stale stale bot commented May 17, 2020

This issue has been automatically marked as stale because it has not had recent activity. We haven't had the time to address it yet, but we want to keep it open. This message is just a reminder for us to help triage issues.

@stale stale bot added the stale label May 17, 2020
@alanna
Copy link
Contributor

@alanna alanna commented May 18, 2020

@contraexemplo are you still looking into this? Do you think it's worthwhile?

@stale stale bot removed the stale label May 18, 2020
@contraexemplo
Copy link
Author

@contraexemplo contraexemplo commented May 18, 2020

@alanna We had a few issues with GitBook earlier this year (as stated in some comments above) and by the end of last year, but since then things have been pretty stable from a infrastructure standpoint. They're starting to add multilingual functionality (see https://blog.gitbook.com/changelog#2019-12-26) and allow clients with certain paid plans to enable PDF exports (https://blog.gitbook.com/changelog#2019-12-12).

However—and this is probably going to be true for a long time if not for as long as GitBook exists— they still remain a closed source platform with a closed development that is sometimes quite difficult to contact (and this will always introduce some kind of risk—like that episode in which our documentation was unavailable for almost a day, or that time our images would break within hours). They have all the power to remove functionality we use extensively, or limit our actions in some way.

In my opinion, our docs as code approach works fantastically, and this shouldn't change. But we still should think about "freeing" our docs from a platform that we can't control as much as we wish, and collaborate with projects that are more aligned with our values.

Moving to another platform would still be extremely time-consuming, though, even if it is compatible with Markdown. And—I have to reiterate as this is my greatest fear—it has to be done strategically to avoid multiple migrations over time (like it happened on a research project I worked for in the past).

@contraexemplo
Copy link
Author

@contraexemplo contraexemplo commented Jun 16, 2020

Here are my findings so far

  • Read the Docs seemed promising, but I don't think it's the platform that will better fit our needs. While they support Markdown, configuring it can be quite intimidating and tiresome. It would require someone to have a good amount of familiarity with Python, and while I am comfortable working with Python builds, someone else may not. I'm trying to aim for maintainability while keeping in mind the bus factor.
  • Docusaurus and Docsify seem to be very fitting, and they remind me a lot of what GitBook used to be. In fact, while reading Docusaurus' introduction, I was surprised by the mention of this issue from Redux that mentions all the problems we're currently having! In 2018!

One other thought: when we do revamp the main Redux docs content, I would want to start moving around a bunch of our pages - recategorizing existing pages, as well as merging/changing others. It would be really beneficial if there's a good redirect solution as part of this. For example, if "Immutable Update Patterns" got moved from /structuring-reducers/immutableupdatepatterns to, say, /reducers/immutable-update-patterns, then I'd want to have a redirect in place so that external links don't break.

Their solution ended up being Docusaurus deployed with Netlify. They address custom redirects directly on Netlify, which also makes the case for a Docsify adoption. Here's the issue in which they test Docusaurus and Netlify, by the way.

What I'm planning to do next

I'll test both documentation software on Netlify with a mirror of our docs. I want to test:

  • Our docs' compatibility level with their Markdown flavor
  • The amount of time it takes to get a working proof-of-concept
  • How easy it is to make contributions
  • If Netlify redirects will be enough to address our issues with frequently-changing-URLs

I'll also investigate all of our deployment options if we decide not to use Netlify's services. I'm hoping to update this issue soon with a list of requirements to execute this project, as well as an estimate of how much time it would take to get a stable build for production.

@alanna
Copy link
Contributor

@alanna alanna commented Jun 17, 2020

Sounds great @contraexemplo ! Thanks for the update.

@znarf @piamancini or anyone else - if you have any requirements for our docs solution please let Anna know.

One thing that would be helpful is an easy way to host multiple docs, such as seperate ones for Open Source Collective and Open Collective Foundation, without needing to do a lot of configuration, etc.

@jaskiratsingh2000
Copy link
Member

@jaskiratsingh2000 jaskiratsingh2000 commented Jun 17, 2020

Hi, @contraexemplo Good research!

Well, I always prefer having those documentation platforms which have better easiness that means which can be used by "non-tech" people to for their contribution. Open source communities merely depend upon the contribution and documentation contains valuable inputs for various activists like "Developer". "Designer","Researcher", "Marketer", etc. So it is not necessary always that they contributors we receive will only be the developer rather we would be receiving many contributors who work in various fields and these all activist have to put input or maintain things at their end when it comes to maintai9niong their field documentation.
So I think this is the reason we should those platforms which are easy and few clicks away.

Copy link
Contributor

@piamancini piamancini commented Jun 17, 2020 — with Octobox

Just that Docusaurus is a collective so bonus points for that.

@Betree
Copy link
Member

@Betree Betree commented Jun 17, 2020

Thank you for this research @contraexemplo.

The points you made about Gitbook are very valid. I want to point out that despite these bugs and the decreasing trust that we have toward their service, Gitbook also still has some arguments in their favor: mainly a nice UI, and the ability to easily create new documentations and host them on their own domains. Plus it's already there and working.

As a general practice, we like to use hosted services. We avoid deploying tools ourselves because it's time consuming and, as you said, bus factor. I guess we could try a solution deployed on Netlify, because once it's configured the maintenance work required is very low.

I'm looking forward the results of your experiment, it will be quite important to make an informed decision.

@contraexemplo
Copy link
Author

@contraexemplo contraexemplo commented Jul 1, 2020

Hello! I'm here with a more complete perspective about this issue, hopefully. The two questions we need to answer here are:

  1. Does this make technical sense?
  2. Does this make economical sense?

Summary: to me, it makes some technical sense — switching platforms would allows us to control a little more our infrastructure, improve our external contribution process, and get access to localization functionality that may be very important in the future —, but (and this one is a pretty big but), it may not make economical sense as we're still navigating a pandemic (and current resources would be better used somewhere else), and our current documentation solution still meets our current needs. As Open Collective discusses goals and needs frequently, I believe that a change in demands would be appropriately addressed if and when the time comes. I invite you to chime in and weigh the pros and cons.


I'd like to preface this by mentioning that both of them are on Open Collective and they are really great tools.

I'm really, really, really impressed with Docsify — it was by far the easiest to deploy locally with almost no changes to our current documentation as the configuration is really simple. I was even able to deploy a proof-of-concept on Netlify in less than 30 minutes: https://musing-brattain-657da9.netlify.app/ As it is, my proof-of-concept is not perfect (I would need to solve conflicts related to file names, images and shortcodes), but I did this with almost no need to edit our files in a different way — and it generates a pretty light website too! Docusaurus, on the other hand, needs way more dedication — and I found it quite difficult to make a successful deploy with little editing. If we were to choose one, I would recommend Docsify for making it really easy to maintain and deploy documentation.

As I'm still exploring Netlify as a tool since I'm still new to their product, I estimate it would take me two working weeks, working 4 hours a day, to fully migrate from GitBook (total of 40 hours). The only things I'd need from the Engineering team would be related to setting up a Netlify account for Open Collective (if there isn't one) and domain preferences.

So, in the end, we have two choices: migrating or letting our documentation be. To GitBook's credit, they are getting better at dealing with incidents — and our latest issue was ultimately solved. They offer convenience at the expense of some level of difficulty to coordinate external contributions outside GitBook's panel and control. Their interface is easy to navigate, and core contributors have access to a number of functionalities through their dashboard that makes it worth a lot of praise. They're growing and learning, just like us ­— and that means that sometimes, we'll stumble upon a few issues.

@jaskiratsingh2000
Copy link
Member

@jaskiratsingh2000 jaskiratsingh2000 commented Jul 1, 2020

@alanna
Copy link
Contributor

@alanna alanna commented Jul 1, 2020

Thank you @contraexemplo ! I've brought this to the attention of the team and we'll get back you soon.

@alanna
Copy link
Contributor

@alanna alanna commented Jul 6, 2020

We have discussed it and decided we want to go ahead with migration to a new platform, and we've approved a budget for @contraexemplo to lead the project. It seems like Docsify is the way to go but we'll leave that to Anna to confirm. We want a platform which is open source and is a Collective as well as meeting the other requirements.

@Betree
Copy link
Member

@Betree Betree commented Jul 8, 2020

@contraexemplo From what I understand, any update to the docs will require a new deploy on Netlify. How does that take place, is it an automated process triggered on edit or every xx minutes/days? Also do you know what's the approximate build time?

We used to use Netlify to host our styleguide, but moved away because there are two limitations with the free plan:

  • No team collaborators
  • Max 300 build minutes per month

The basic plan to get rid of these limitations (which adds 3 team members, 1000 build minutes) is $45/month.

We've switched the styleguide to https://render.com, which offers unlimited collaborators and build minutes for static websites with pretty much the same features than Netlify has.

@contraexemplo
Copy link
Author

@contraexemplo contraexemplo commented Jul 16, 2020

@Betree It takes a total of 14 seconds (7 seconds to build and 7 seconds to deploy, according to Netlify). A build and deploy is triggered every time someone add commits to the main branch. I wonder if their continuous integration with GitHub (especially generating previews when someone opens a pull request) may also influence in the # of builds per month? It isn't quite clear from their blog post on the matter.

Could you please tell me a bit about your workflow with Render? How similar to Netlify is it in terms of processes? (You can message me privately on Slack if you wish to share more information on this.)

@Betree
Copy link
Member

@Betree Betree commented Jul 20, 2020

It takes a total of 14 seconds

Good to know, that's super fast!

I wonder if their continuous integration with GitHub (especially generating previews when someone opens a pull request) may also influence in the # of builds per month?

From what I remember, it does. That was the main reason why we reached the limit so quickly.

Could you please tell me a bit about your workflow with Render?

In terms of process, it's very similar to Netlify. You add a new project (new service) by selecting the repo and then it auto-deploys whenever someone push on master.

@contraexemplo
Copy link
Author

@contraexemplo contraexemplo commented Aug 13, 2020

Long-due progress update (sorry for taking so long, I had to take care of some personal matters):

  • Instead of trying to upkeep the latest version of the docs on my current fork, I decided to establish a point of time and later merge any changes to content made after my fork. I'll send a notification for everyone with some days of advance for when I'm be ready to do so so we can coordinate this.
  • I was spending most of my time with a local build, adding any features we already have on GitBook plus testing those who were particularly problematic there. Docsify heavily depends on snippets of code/add-ons written in JavaScript so that gives us quite a lot of flexibility even to fork them and make any changes we want.
  • However, when I finally set up a Render environment, I ran into a few problems with the search and some images (see https://open-collective-docs.onrender.com). I'm investigating them.

Since deploying with Render is our goal, I'll abandon the local environment for the most part and run a lot of tests on my build there. I should also test things like URL redirects to make sure that's a painless (or at least well-documented) process too.

I've set up a deadline for August 24 (that's 12 days from now).

@contraexemplo
Copy link
Author

@contraexemplo contraexemplo commented Aug 24, 2020

Hey. I had ~10 days of downtime after my current glasses broke a day after I posted the last update — I wasn't able to work for more than a couple of hours with my old ones without some awful side effects. I got a new pair this weekend and will proceed with what I had planned this week instead.

@alanna
Copy link
Contributor

@alanna alanna commented Aug 24, 2020

@stale
Copy link

@stale stale bot commented Dec 6, 2020

This issue has been automatically marked as stale because it has not had recent activity. We haven't had the time to address it yet, but we want to keep it open. This message is just a reminder for us to help triage issues.

@stale stale bot added the stale label Dec 6, 2020
@alanna
Copy link
Contributor

@alanna alanna commented Dec 6, 2020

@contraexemplo - what is the status of this project?

Copy link
Contributor

@piamancini piamancini commented Dec 9, 2020 — with Octobox

We recently found that next has a new option for docs @contraexemplo was going to look into it

@stale stale bot removed the stale label Dec 9, 2020
@contraexemplo
Copy link
Author

@contraexemplo contraexemplo commented Dec 21, 2020

Hello! First of all, I'm sorry for being absent for so long. The TL;DR is that this semester... wasn't what I expected it to be: I had COVID-19, my partner suffered an accident and I was forced to re-evaluate the priority a lot of things for a while. But I'm back!

@piamancini mentioned Nextra on Twitter. It isn't production ready yet —there's a few reported bugs here and there. It's Markdown compatible and promise to have a less scary configuration/deployment method. It also shares a good bunch of functionalities with other solutions I've seen.

I have quite a good amount of catch up to do with Docsify so I'm going to run some tests with Nextra on the side too.

@Betree
Copy link
Member

@Betree Betree commented Dec 22, 2020

Welcome back @contraexemplo, I hope things are better for you now 🤞

Nextra looks good, and the fact that it build upon NextJS is definitely an advantage for us. But as you mentioned, they clearly state that it's not production ready yet.

We should be extra careful about adopting such project at an early stage for our production documentation. If we decide that it's the one we want to use in the future, maybe we can wait for it to be more mature. To be honest Gitbook hasn't been so bad lately, nothing like the bugs we faced a few months ago. I wouldn't be against delaying a bit, though I think we still want this migration at least to move to an open source solution.

@contraexemplo
Copy link
Author

@contraexemplo contraexemplo commented Dec 22, 2020

@Betree Thank you, it's good to be back! Things are definitely better on my side!

I agree 100% with you, there's quite a road ahead of Nextra still and OC is at a moment where stability is a must.

@stale
Copy link

@stale stale bot commented Jul 21, 2021

This issue has been automatically marked as stale because it has not had recent activity. We haven't had the time to address it yet, but we want to keep it open. This message is just a reminder for us to help triage issues.

@stale stale bot added the stale label Jul 21, 2021
@BenJam BenJam added this to To do in Documentation Jul 27, 2021
@shannondwray shannondwray moved this from 👉 To do to 👇 In progress in Documentation Aug 31, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Documentation
👇 In progress
Google Season of Docs 2019
  
Awaiting triage
Development

No branches or pull requests

8 participants