search

opencollective / opencollective

We're tracking all our Issues, RFCs and a few other documents in this repository.
https://opencollective.com
MIT License
2.01k stars 370 forks source link

Refactoring Open Collective's help docs #1612

Closed alanna closed 5 years ago

alanna commented 5 years ago

I'm working on a project to clean up and improve our help documentation, and I'm going to use this issue to get input and develop a plan.

Help docs currently live in multiple places:

We also offer support via email and slack.

I propose:

So: which ONE place should help docs live - Website, Github Wiki, or Discourse Forum?

Betree commented 5 years ago

This is great initiative @alannallama, I wrote some documentation a few weeks ago and I didn't publish it cause I didn't know where to do it - so :+1:

I'll add a fourth option that is what @piamancini started using recently: https://www.getoutline.com. It looks nice but I don't know the tool and we must ensure it has the following features if we want to centralize docs on it:

TLDR ; Github Wiki is my preferred choice, but if we can get the same features from it "Outline" has a better UI.

alanna commented 5 years ago

Gitbook is another tool similar to Outline, which I have used before quite a lot.

HipsterBrown commented 5 years ago

@alannallama I use Gitbook for the Tessel project docs (https://github.com/tessel/t2-docs) and it's a pretty nice experience, especially with automatic deployments. I really enjoy the glossary feature.

My biggest knock against the GitHub wiki is that it is not possible to open a pull request for the information there.

gusaus commented 5 years ago

Hi @alannallama - There's some related discussion around using https://readthedocs.org/ in the #documentation Slack channel.

@xdamman set up https://github.com/opencollective/documentation/ to house the documentation and related issues but here hasn't been much recent progress or activity.

Might still be a good option if there’s a process to onboard and sustain community members interested in contributing? https://github.com/opencollective/documentation/issues/1

alanna commented 5 years ago

@gusaus - yes good points. We have a few different groups of users of documentation:

1) End-users like backers, sponsors, etc who want to know basically how the system works 2) Core contributors who need details about all the more advanced features 3) Host admins who use still another feature set 4) Developers interested in contributing to the codebase or deploying an instance themselves 5) Internal Open Collective team members (stuff like managing the tax forms we collect, responding to support requests from users, reporting bugs, etc)

There are documentation tools more suited to different kinds of users. But I'm thinking we should just pick one and centralise it in one place.

Criteria include being open source, transparent to all, able to be updated relatively easily. Several good tools mentioned meet all those criteria (Outline, Gitbook, our website, GitHub wiki, ReadTheDocs). For me what's important is we make it super clear, link it everywhere, and stick with it.

alanna commented 5 years ago

@piamancini @xdamman @znarf - Do you want to weigh in on this, or should I just pick an approach and go for it? I don't know details of the decisions to set up the existing documentation the way it is, so please let me know if there's context I am missing.

gusaus commented 5 years ago

@alannallama Reading back through the logs in #documentation might provide some context around previous decisions and recommendations from community members. https://opencollective.slack.com/messages/C9767R4V9

Seemed like there was some consensus around ReadTheDocs + the stand alone docs repo https://github.com/opencollective/documentation

alanna commented 5 years ago

After some discussion about the help docs situation, we are leaning toward using Gitbook. If anyone has a comment about that, let us know soon because we're getting close to beginning the work.

gusaus commented 5 years ago

I think it was pretty much a tossup between ReadTheDocs and Gitbook when we previously evaluating. Aside from many projects using RTD, they also provide good material to fork and build upon for organizing chapters and events https://github.com/opencollective/documentation/issues/2 For example http://www.writethedocs.org/organizer-guide/

Then again Gitbook also works very well https://organize.djangogirls.org/

Has there been any consensus on using the documentation repo, slack channel, and assembling a docs team? https://github.com/opencollective/opencollective/issues/1612#issuecomment-452916768

alanna commented 5 years ago

@gusaus thanks. We'd love to have more people involved in docs, and also to pay them via our Open Collective, of course. I'm thinking that a basic foundation of documentation set up in a clear system will really facilitate ease of contribution. So I'm doing a first pass. Once that's done, we'll announce it along with an invitation for others to participate.

alanna commented 5 years ago

Draft is in progress here: https://opencollective.gitbook.io/help

It has most of the documentation from the various sources, but still has a ways to go to polish it and bring it up to date. It's also missing some newer features, but I'm working on it currently.

alanna commented 5 years ago

OK, we're getting ready to launch the new help docs! See it at https://docs.opencollective.com

alanna commented 5 years ago

List of links to docs

Theses need to be added or updated for the new help docs:

@piamancini @xdamman where else are the wiki or faqs linked from?

xdamman commented 5 years ago

Why not keeping a FAQ? I love browsing FAQs when I'm on a website that I'm trying to understand.

For the onboarding emails, not sure in which particular you wanted me to add the link and where So I've just added this to the day 2 on boarding email:

If you have any questions, have a look at our documentation and help website on https://docs.opencollective.com. We have also published this helpful guide on our blog: Ten Steps to Successful Open Source Crowdfunding

alanna commented 5 years ago

@xdamman all of the FAQ content has been moved to the gitbook - I didn't leave anything important out. The point of this project was to centralise everything into one place. If we have multiple places, they will quickly get out of sync and we'll be right back where we started with help all over the place and things out of date. So I feel strongly that we should remove the FAQ from the website and direct all links to the docs.

xdamman commented 5 years ago

Not arguing against that, just arguing that people like look for a FAQ. Maybe there could be such section in the docs? Or you think that even that is hard to maintain? I guess it’s a balance between that and what the users expect.

alanna commented 5 years ago

I see. Well, each of the chapter top level pages are basically FAQs. But if someone is specifically scanning for 'FAQ' they might not realise this from the table of contents. The thing is, there is actually a huge amount of info that can be considered FAQ, which is why there's one for backers, one for core contributors, one for hosts, etc.

We could try to boil it down to the most important and put a page called FAQ in the gitbook. What do you think are actually the most F asked Qs?

xdamman commented 5 years ago

Yeah maybe the FAQ is just short answers with a link to the appropriate place in the documentation. It’s an easy way for people to scan through it. Think of it as another entry point.

What are the most frequent questions? You tell me ;-) From my side I’d start with:

Another idea would be to have a glossary to help define the different terms. What do we mean by host, collective, admin, backer, organization, etc. It will also be helpful for the team! :-)

alanna commented 5 years ago

@xdamman I put the FAQ as suggested on the welcome page, and changed the 'roles' page to 'glossary' because that's what it was anyway.

xdamman commented 5 years ago

Mmmm... but there is also a FAQ in About: https://docs.opencollective.com/help/about What about making FAQ at the same level of "About"? (and link to it from the welcome page)

alanna commented 5 years ago

I'm not 100% sure what you mean, but feel free to move stuff around!

On Thu, 14 Feb 2019 at 00:26, Xavier Damman notifications@github.com wrote:

Mmmm... but there is also a FAQ in About: https://docs.opencollective.com/help/about What about making FAQ at the same level of "About"? (and link to it from the welcome page)

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/opencollective/opencollective/issues/1612#issuecomment-463163652, or mute the thread https://github.com/notifications/unsubscribe-auth/AFPn_ubZZxl5_3cGMX0coYJmqFmkIeR8ks5vM_ZUgaJpZM4Z0lop .