Creating a style guide for Open Collective's docs

[contraexemplo]

The problem

From GitHub wikis to GitBook, our docs have gone through immense changes over the years. And with so many people with different ideas of how it should be like, a conflict of writing styles and "sequential logic" has become more apparent.

The solution

The creation of a style guide will help us write consistent documentation for our users and contributors. It will provide guidelines to assist every writer on how to describe certain processes, add a certain type of media or create a new section of the documentation.

A few initial questions

• We have the advantage of mirroring our documentation on GitHub. This gives us access to commands like git grep to search our entire repository. What naming scheme should we adopt for media like images and GIFs? Is section_page_vVERSION_NUMBER a good one naming scheme?
• Should we consider adopting a particular variant of English as the one follow when writing our docs or should we embrace the international nature of our organization?
• GitLab has a no special type policy for their documentation. Would it be a good idea to adopt a single template for ours? What is your idea of a perfect template?
• What do you think about adopting an archiving policy for our documentation when mentioning external pages beyond our control? We could use services like the Internet Archive to save them.

Issues we should address on our style guide

This is not a definitive list... yet.

• How to structure our documentation: naming a page, creating a new page, creating a new section, creating groups of pages.
• Overall writing style (informal, friendly)
• Adding media to the documentation
• Formatting, using Markdown
• Templates per topic (i.e. API)?
• Using GitBook or GitHub to add pages
• Terminology (referencing Alanna's wonderful docs on this)
• ... Any other suggestion you may have.

[alanna]

Anna and I discussed the naming convention for images, and decided to go with a simple, manual solution for now (as opposed to something that relies on a script). It will probably include a reference to the page and section, plus a couple keywords about content. In the future if we move images around or create new ones we'll need to remember to rename them accordingly. Anna will settle on a conclusion and create guidelines for this.

The docs are mainly in American English so far, as the company started there and many users are there. I don't really mind which English we use, but it should be consistent. I think probably American English to match our marketing materials, etc.

Anna and I talked about templates and decided that we'll know a lot more closer to the end of the project, and that this question is really about how others can contribute to docs in the future while maintaining quality and consistency. So we should circle back to this question later.

Re: archiving. We have very few links to external static content. Almost all links are internal (to docs, the app, our github, etc) and maintained by us, and external links are to tools or services that are dynamic. So we will handle any broken links manually for the time being and not archive content.

[Betree]

Would it be a good idea to adopt a single template for ours? What is your idea of a perfect template?

Yes, Gitlab's template seems really clear and flexible enough to me.

Using GitBook or GitHub to add pages

A big strength of GitBook is how well it integrates with GitHub. I like the integrated editor they offer but only Open Collective core contributors can use it. As such I don't see any drawbacks to use both at the same so if it doesn't create any formatting or naming issues I wouldn't force the use of one or another.

[xdamman]

This looks great. I'd just like to add a clear contribute.md specifically targeting people who would love to contribute to the documentation. Maybe the template could always have a call to action to improve that particular page. Maybe, like on wikipedia, there could be a tag or a line at the top that says on some pages: "this page needs illustrations, more references, more examples, etc.".

I'd love to see a collective emerge to take care of developing and maintaining a documentation to help collectives get started and be sustainable (maybe also create opencollective.com/docs in the same way that we have https://opencollective.com/engineering and https://opencollective.com/design?)

Following the same idea, I wonder if this issue (and subsequent ones) shouldn't be moved to https://github.com/opencollective/docs/issues ?

[piamancini]

@contraexemplo This is great and it lays a framework for consistency in future iterations.

I'd just like to add a clear contribute.md specifically targeting people who would love to contribute to the documentation

+1

I'd love to see a collective emerge to take care of developing and maintaining a documentation to help collectives get started and be sustainable

@xdamman this has already been created: https://opencollective.com/documentation

[xdamman]

Ah great, brilliant! Let's add @contraexemplo to it.
For consistency, what about either rename it to /docs (or rename docs.opencollective.com to documentation.opencollective.com but that seems harder).

[contraexemplo]

@xdamman

Following the same idea, I wonder if this issue (and subsequent ones) shouldn't be moved to https://github.com/opencollective/docs/issues?

Maybe https://github.com/opencollective/documentation/issues? I opened this issue in particular over here per Alanna's requests. But I see no problem in moving discussions to that repository.

This looks great. I'd just like to add a clear contribute.md specifically targeting people who would love to contribute to the documentation. Maybe the template could always have a call to action to improve that particular page. Maybe, like on wikipedia, there could be a tag or a line at the top that says on some pages: "this page needs illustrations, more references, more examples, etc.".

Yes, I completely agree with this. During my project, the last pages I'll revamp will be the ones related to contributing to Open Collective as an open project. This should include things like development, design, translation and documentation.

[contraexemplo]

@Betree True, I love GitBook's integration with GitHub. And the Welcome page at https://docs.opencollective.com already has a summary on what to do to contribute to the documentation in terms of tools and procedures for external contributors with no access to GitBook's internal tools. It needs a bit of work, but it covers a good amount of information already.

[xdamman]

I'm confused. What's the difference between https://github.com/opencollective/docs and https://github.com/opencollective/documentation?
Given that the subdomain is https://docs.opencollective.com I would consolidate everything under "docs" to avoid any confusion (including for the slug of the collective, see #2389 (comment))

[contraexemplo]

@xdamman https://github.com/opencollective/documentation is where files from https://docs.opencollective.com are synced to. Any edit on GitBook results in a commit over there, and approved PRs can also modify content.

On the other hand, https://github.com/opencollective/docs seems to be an abandoned repository?

Making a few tests, Open Collective + docs seems to point people to docs.opencollective.com while Open Collective + documentation redirects them to opencollective/documentation. That's certainly something to think about.