docs: Make the docs available open source

[denderello]

Now that we have the new version of the docs available I wanted to ask of making the project available open source. That would give us the opportunity to receive PRs from the users as well as adding a button for this on every page of the docs.

Question is would could hold us back to do so? @zyndiecate thought of things like credentials in the commit history. Anything else?

List of things to be considered (Please add items you find missing)

• [x] Decide on content license
• [x] Decide whether we need an official user agreement before accepting contributions
• [x] Decide whether we want to make the app or only the content public
• [x] Start a new, clean public docs repository
• [x] Add a "Fork me" (or similar) notice visible everywhere in the docs

[denderello]

@marians: what's your opinion on this?

[marians]

My thoughts:

• No problem with bringing the Markdown content to public
• Not sure about the rest of the app. Would like to know how you all think about this. (Just look at the root folder of the giantswarm/docs repository)
• I'd like to start from scratch with issues, commit history and pull requests. Everything I wrote in there was written with Giant Swarm as an audience in mind, not for the public.
• We probably need a content license
• To accept pull requests, I'd like to discuss whether we need a contribution policy. Something people implicitly acknowledge when sending pull requests. (Accept that their contribution falls under our license.)

[denderello]

Not sure about the rest of the app. Would like to know how you all think about this. (Just look at the root folder of the giantswarm/docs repository)

Maybe we should finish some issues (like #72 ) before that to clean some things up.

I'd like to start from scratch with issues, commit history and pull requests. Everything I wrote in there was written with Giant Swarm as an audience in mind, not for the public.

+1

We probably need a content license

Sounds reasonable. Who can make a decision on this? The CoreOS guys just use Apache for the files. https://github.com/coreos/docs

To accept pull requests, I'd like to discuss whether we need a contribution policy. Something people implicitly acknowledge when sending pull requests. (Accept that their contribution falls under our license.)

Not sure if we need a CLA for this.

[marians]

After a night of sleep, I'm in favor of publishing the content folder without the rest of the app and template logic. Main reason: Users will find their way to the relevant file much easier than if they had to dig through all files. Minor reason: I don't want to open a discussion about details apart from content with the users.

[xh3b4sd]

I like. Do you have an idea how the content separation could be integrated into your dev workflow in a comfortable manner?

[marians]

Currently I think that adding a git clone to the make build target would be okay.

[marians]

See also #46

[denderello]

Like the idea too.

Would be clone be ok for you when it comes to making changes? People creating PRs will never have the chance to see the rendered docs on their local machine and so will have to create changes blindly. Also you will have to clone every PR from a cloned repository to your machine and run it with our setup to check if the PR is not breaking anything.

[marians]

People creating PRs will never have the chance to see the rendered docs on their local machine and so will have to create changes blindly.

That's clearly a major downside.

Checking out a particular branch of the cloned sub-dir is also slightly less convenient than having the entire code in one repo and switching branches there.

[denderello]

Just had a look at the CoreOS docs repository and they do it the same way as @marians suggested. Maybe we should just give it a try.

[marians]

A really good reason to have a content-only public docs repository just crossed my mind. If we decided to integrate the documentation into our main site, say under https://giantswarm.io/docs/, we probably wouldn't have to touch the content repo at all. That means: No confusion for contributors. I like that.

[denderello]

Ok, I think we have an agreement then that we can create a public repository for just the raw content files.

Maybe we will have to think again about how to integrate them into the built process.

On Thu, Feb 12, 2015 at 11:38 AM, Marian Steinbach <notifications@github.com

wrote:

A really good reason to have a content-only public docs repository just crossed my mind. If we decided to integrate the documentation into our main site, say under https://giantswarm.io/docs/, we probably wouldn't have to touch the content repo at all. That means: No confusion for contributors. I like that.

— Reply to this email directly or view it on GitHub https://github.com/giantswarm/docs/issues/70#issuecomment-74050248.

Dennis Benkert Developer @ Giant Swarm GmbH +49 151 191 88 094 dennis@giantswarm.io @denderello

Web: http://giantswarm.io Twitter: http://twitter.com/giantswarm

Handelsregister: Amtsgericht Köln, HRB 81484 · Sitz der Gesellschaft: Köln · Geschäftsführer: Timo Derstappen, Henning Lange, Oliver Thylmann

[marians]

Now that it's decided that we would publish a content-only repo, licensing becomes easier. The Apache 2 license we use is made for source code and IMHO not particularly well suited for content (text and images).

For content, I recommend a Creative Commons (CC) license. The CC equivalent to Apache 2 would be CC-BY, which basically only requires attribution. See http://creativecommons.org/licenses/by/4.0/

[denderello]

I am fine with CC-BY

[marians]

License: According to a slack discussion, we'll use CC-BY-SA (share-alike).

[marians]

Here is a README proposal for the public Docs content repository. I welcome your feedback here in the private space. :)

---

Giant Swarm Documentation Source

This is the source for all Giant Swarm documentation.

Go to http://docs.giantswarm.io/ for the production version of our documentation. That version also includes integrated search.

Contributing

This repository is public to facilitate content quality and encourage contributions. We appreciate all contributions, including corrections and suggestions for improvement.

The best way to contribute changes are pull requests. Please note the following regarding pull requests:

• Please make one pull request per topic/issue. Avoid putting several non-related issues in a single pull request!
• When doing a pull request, please remember you accept that your contribution will be published under the Creative Commons referenced below. Giant Swarm will be able to use your content without restriction. Giant Swarm is not obliged to list you as the author of your contribution, but will attempt to do so where possible.

Questions, comments and content requests can be addressed by adding an issue to this repository.

License

The content in this repository is licensed under the Creative Commons Attribution ShareAlike license.

For attribution, please use either:

• Giant Swarm
• giantswarm.io

Last but not least, be sure to link to your contributions. We appreciate your effort to help us improve!

[kordless]

I've update the comment making primarily grammar/vernacular corrections. I'm not sure that's the best strategy here, given we don't get revisions in comments, but it works. Next time I'll just do a new comment.

[marians]

Here is the initial import to the public repo: https://github.com/giantswarm/docs-content/pull/2

[marians]

As for this part, "Decide whether we need an official user agreement before accepting contributions", which I've added before: We are for now going without anything like this. Many other companies only rely on showing their contribution policy somewhere. We have this now in the README, so we assume we're fine.

[marians]

The content repo is public now: https://github.com/giantswarm/docs-content

[marians]

Happily closing this issue :)