opencollective / documentation Goto Github PK

Currently, our docs have two FAQs under the (deprecated) section "Backers and Sponsors":

• https://docs.opencollective.com/help/backers-and-sponsors (which seems to be more focused on individual contributors)
• https://docs.opencollective.com/help/backers-and-sponsors/sponsor-faq (which is focused on organizations)

1. Should we create different pages and subpages for individuals and organizations? A lot of info from that section is specific for organizations.
2. How should we call contributions from organizations? Sponsorship?

We had a small incident with broken links, so I figured it would be useful to write a post mortem with my findings:

• A group of pages called collective will get the following URL: docs.opencollective.com/help/collectives. All belonging pages will follow that naming scheme, i.e. the Creating a Collective page receives .../creating-a-collective.
• The same will happen with main and subpages. The page Collectives has a couple of subpages. Its URL is also https://docs.opencollective.com/help/collectives. So GitBook ignores the group of pages and only renders the main page and its subpages.

Conclusion: GitBook generates URLs to groups of pages and parent pages with the same URL naming scheme. A parent page and its sub pages has more weight to GitBook than a group of pages.

I suspect something similar happened to The Open Collective Way pages, though they simply disappeared instead of just being broken. On my mirror on GitBook, however, everything worked normally. Maybe it was a bug, maybe it was something else. I'm not sure I'll get an answer on that anytime soon.

Questions:

• How should we proceed with more aggressive changes? Should I stage them on a GitBook mirror first? GitBook acts up from time to time.
• There will probably be a couple of broken links on the app as we make changes. Which repository should I search to keep those links up to date? I think I'm able to edit more complex files if the only thing that should be changed are URLs.

I would request the following improvements that can be done in the README:

1. Addition of logo of open collective organization.
2. Addition of link of the slack channel.
3. Adding the guidelines to create how to create a pull request.
4. Addition of contribution guidelines.
5. Structuring the whole readme in different sections as about, communication means, contribution and pull request guidelines.
6. Removing the FAQ section from the README and adding it as separate section in the documentation page.

Further improvements and changes can be done after review from the community members.

Thanks!
Deepak Kumar

All

We use you system a payment collector that produces automagically a accounting report. We need to collect more information about the participants.
We would like to be able, first through your interface, then through an API, theses other characteristics and be able to get them afterwards.
Much thanks

Suggesting changes still mentions the master branch as the branch to receive new changes. Screenshots and text should be updated accordingly.

The two links on the Manual Reporting page are broken.

The current links from manual-reporting.md:

• https://github.com/OpenCollective/opencollective-api/blob/master/templates/emails/group.monthlyreport.hbs
• https://github.com/OpenCollective/opencollective-api/blob/master/cron/monthly/email-report.js#L30

It looks like the correct links should be:

• https://github.com/opencollective/opencollective-api/blob/master/templates/emails/collective.monthlyreport.hbs
• https://github.com/opencollective/opencollective-api/blob/master/cron/monthly/collective-report.js

There are broken images in the documentation, see https://docs.opencollective.com/help/financial-contributors/organizations/gift-cards#faq for example.

Problem seems to come from a3ece2d#diff-0453d5dcc4be328ac7fe8a9c43ba2a4c. Git seems to say I've made some of these changes, but I haven't renamed these files.

@contraexemplo any idea of what could be the reason?

On https://docs.opencollective.com/help/about/company (https://github.com/opencollective/documentation/blob/master/about/company.md#L19) is mentioned "We run our company via an Open Collective...", where "Open Collective" is a link that points into the void.

I wanted to create a PR with the correction, but I am unable to tell which of the hosts/collectives is actually "responsible" (in the sense of the original documentation): https://opencollective.com/search?q=open%20collective .

We decided to use a single repository to track issues across all our projects.

See: https://github.com/opencollective/opencollective/issues

Issues related to the Open Collective documentation are tagged with the label "documentation":
https://github.com/opencollective/opencollective/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation

We are still finding a good amount of dead links ever since we published our new version of the docs. Our contribution guidelines should teach our contributors how to correct that issue. Here's a quick step-by-step guide I wrote on Slack:

1. I visit the master branch on GitHub and read the raw content. https://raw.githubusercontent.com/opencollective/documentation/master/product/README.md
   In this case, this was pointing to backers-and-sponsors/README.md. That whole section became "Financial Contributors" in the new version of the documentation.
2. I find the new page. Here it is: https://github.com/opencollective/documentation/blob/v2/financial-contributors/financial-contributors.md
3. Sometimes, it's just a matter of updating .gitbook.yaml to point that specific address to the right page. But other times (probably when we make aggressive changes to the folder structure--their versioning system doesn't seem to like that much), you'll have to update that link manually.

Our docs have few references to external documentation, but they are all pretty significant: they are either essays written by core contributors, or messages of support and approval from members. In special, since it our docs were first written, Open Collective has abandoned Medium and moved its blog to Ghost. Referencing the right links to the right content here is relevant to those who will discover this kind of content and wish to follow a RSS feed or subscribe to the newsletter. I believe we should update them accordingly.

The documentation currently still lists these:

• Routing number: 123205054
• Account Number: 4866342233

However according to Stripe this is a test account that can not be used in live mode:

So you might want to check your bank account / account number and I'll probably also have to contact Stripe, because due to that error message I won't also be able to change it to the correct number.

Too bad already 40 USD went there on Jul 22 :S
Edit: (And they didn't arrive in our https://opencollective.com/advancedfx yet, so they might be lost.)

We decided to use a single repository to track issues across all our projects.

See: https://github.com/opencollective/opencollective/issues

Issues specifically linked to this repository should contains the label frontend:
https://github.com/opencollective/opencollective/issues?q=is%3Aissue+is%3Aopen+label%3Afrontend

Amount: {500.00}
Reference/Communication: acme/76400
Account Holder Name: CASSIME LINGO
Account Number: 992015155557
Account Type: SAVINGS
Legal Type: BUSINESS
Routing Number: 114924742
Address:
8125 COUNTY ROAD 65
Post Code: 36310
Country: US
State: AL
City: ABBEVILLE

Proposal

This is the current structure of the Welcome page:

Welcome
├── Introductory paragraphs
│   ├── Short description of Open Collective
│   ├── Short description of the goal of our documentation
│   ├── Short instructions to suggest changes to any page
│   └── Short instructions to contact us: email and Slack
├── Overall FAQ
└── How to contribute to these docs

I propose restructuring the page as follows:

Welcome
├── Introductory paragraphs
│   ├── Short description of Open Collective
│   ├── Short description of the goal of our documentation
│   ├── How to explore our documentation
│           ├── Map explaining every section
│           └── Instructions on using the search bar
│   ├── How to contribute to our documentation
│           └──  Points to Contributing > Documentation > Suggesting changes
│   └── Short instructions to contact us: email and Slack
└── Overall FAQ

Documentation map

It should be added after revamping all pages of the documentation. Proposed format:

Name of the section
└── Brief description + link

Contribution guidelines

A draft of the Suggesting changes page is available on my own GitBook. It still needs:

• Higher quality screenshots to add complementary information to every instruction
• Instructions to add new files (media) or pages and sections to the repository

I am in the process of migrating fiscal hosts from US to Europe. From the documentation, nor the UI it is not clear to me how my kiwitcms-europe collective should submit an expense report to my kiwitcms collective so I can zero the funds for kiwitcms and migrate its fiscal host.

Can you give me an example, I will contribute a pull request to the docs to make this clear.

I merged the new organization again and GitBook didn't render it right again (don't worry, I reverted the merge!). So I have a new idea:

GitBook offers the following feature:

• We can sync as many branches as we want from GitHub
• We are also able to transform them into versions (doc version 1.0.0, etc) publicly accessible to anyone or delete a whole deprecated version easily

My meta GitBook showcases this. I set up the open-collectivebranch (https://github.com/contraexemplo/metadocumentation/tree/open-collective) as the main docs/most current documentation and there's a link to the redirect branch (https://github.com/contraexemplo/metadocumentation/tree/redirect) with the old version of said documentation. We could do the same for the new organization while keeping the old version live as well.

Open Collective will release an updated version of the Create Collective form, including the GitHub flow. Pages that include information related to those flows need to be updated.