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 · 10 comments
Open

A new home for Open Collective's documentation #2595

contraexemplo opened this issue Nov 4, 2019 · 10 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?
@contraexemplo contraexemplo self-assigned this Nov 4, 2019
@alanna

This comment has been minimized.

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?

@jaskirat2000

This comment has been minimized.

Copy link
Member

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

This comment has been minimized.

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

This comment has been minimized.

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

This comment has been minimized.

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

This comment has been minimized.

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

This comment has been minimized.

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

This comment has been minimized.

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

This comment has been minimized.

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

This comment has been minimized.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Google Season of Docs 2019
  
Awaiting triage
6 participants
You can’t perform that action at this time.