A new home for Open Collective's documentation #2595
Comments
|
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? |
|
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. Thanks |
|
@znarf - did you want to add the comments here that you brought up in the meeting? |
|
@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. |
|
@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). |
|
Just a small note, docsify and docusaurus are on Open Collective, so it's always a plus when picking a tool. |
|
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/ |
|
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. 👍 🎉 |
|
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. |
|
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. |
|
@ericholscher We had an incident with our current documentation platform last week that left me curious about how RTD deals with downtime.
|
|
Bumping this, Gitbook broke the images on https://docs.opencollective.com/help/collectives/subcollectives for the second time and it's pretty frustrating. |
|
@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. 🤔 |
|
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. |
|
@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? |
|
Extracted the issue to #2917. I think we can send the text or a link to the issue directly to Gitbook. |
|
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. |
|
@contraexemplo are you still looking into this? Do you think it's worthwhile? |
|
@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). |
Here are my findings so far
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 nextI'll test both documentation software on Netlify with a mirror of our docs. I want to test:
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. |
|
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. |
|
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. |
|
Just that Docusaurus is a collective so bonus points for that. |
|
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. |
|
Hello! I'm here with a more complete perspective about this issue, hopefully. The two questions we need to answer here are:
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. |
|
Great research Anna! I can help you with migration if needed.
Thanks
…On Wed, 1 Jul 2020, 9:15 pm Anna e só, ***@***.***> wrote:
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
<#3165>. 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.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#2595 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/ACOBHK5PLELJCZCPVCB3BQ3RZNK3FANCNFSM4JIYWVWA>
.
|
|
Thank you @contraexemplo ! I've brought this to the attention of the team and we'll get back you soon. |
|
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. |
|
@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:
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. |
|
@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.) |
Good to know, that's super fast!
From what I remember, it does. That was the main reason why we reached the limit so quickly.
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. |
|
Long-due progress update (sorry for taking so long, I had to take care of some personal matters):
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). |
|
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. |
|
Sorry to hear about the glasses situation! That sounds frustrating. Keep us
posted :)
|
|
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. |
|
@contraexemplo - what is the status of this project? |
|
We recently found that next has a new option for docs @contraexemplo was going to look into it |
|
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. |
|
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. |
|
@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. |
|
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. |
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:
My insight
I believe that a perfect documentation tool for Open Collective should fulfill the following requirements:
Negotiable features:
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
The text was updated successfully, but these errors were encountered: