Changes from GitBook might alter our docs

[dpordomingo]

I commented on https://github.com/src-d/sourced-ce/commit/c9cdd13db5007d5ad07d1b87911c1b51bbc35dc4 from @vcoisne, about 10 different changes that could alter or damage our docs if not done on purpose.

examples:

• CONTRIBUTING.md and LICENSING.md moved outside of its expected place (the second one was already fixed by #233),
• broken anchors in README.md,
• shortened titles.

If they were done on purpose, we could discuss them separately. If they were done automatically by GitBook UI, I think we should reconsider using it to edit our docs.

[carlosms]

@dpordomingo let's fix what is actually broken (contributing, anchors) and assume all changes were intentional.

@vcoisne let's please follow the normal github workflow and do all future edits as pull requests. If you really prefer to edit directly on gitbook, this link shows how to edit on a new branch that can be used to open a PR: https://www.thegizraway.com/gitbook_and_github_workflow.html

[carlosms]

Also: the ```text code blocks should be reverted to the proper syntax highlighting we had before.

[dpordomingo]

I can fix what you suggested:

• links (only the already spotted bugs, not checking all other links),
• move CONTRIBUTING.md to its standard location,
• code syntax.

But I would like to confirm the following:

• Can we assume that the broken links are only the ones I found?
• Can we assume all the other automatic changes done by GitBook (e.g. titles shortening [1], [2], [3])?

[carlosms]

• Can we assume all the other automatic changes done by GitBook (e.g. titles shortening [1], [2], [3])?

Why do you say those changes are automatic? They look like intentional changes to me. Let's leave the contents as they are, and just focus on fixing broken links, code blocks etc.

[dpordomingo]

Per later investigation, I confirmed that each edition made from GitBook UI (no matter what is edited) forces GitBook to parse the whole docs, and format them according to their internal (and not documented) rules.

Some uncontrolled changes are:

• titles are automatically shortened based on the docs SUMMARY,
• docs like LICENSE.md, CHANGELOG.md or docs/CONTRIBUTING.md, being moved somewhere else,
• code syntax defined as text instead of bash or powershell,
• line breaks are lost, so line length is no longer under our control,

PR https://github.com/src-d/sourced-ce/pull/239 rollbacks all the changes made at c9cdd13 by @vcoisne.

We could also disallow GitBook bot to commit to master to avoid these issues.

[vcoisne]

@dpordomingo sorry about that and thanks a lot for fixing. Was not clear to me that we could not make these changes via the Gitbook UI. Is that documented anywhere?

[dpordomingo]

Don't worry @vcoisne, we didn't know about this issue before you tried. We discussed it in slack many months ago, but at that moment all of us did prefer regular PRs instead of web UI, so we didn't document it.

I think we should now consider if we want to migrate our docs to GitBook, and then use GitBook for editing, or keep going with regular GitHub PR workflow. If there is no change in our current way to develop our docs, we should also mention in our company CONTRIBUTING.md, that docs should be edited from GitHub (I'd vote for this option).

So, since #239 reverts all your changes made by c9cdd13, do you remember what did you change there? It would help us to recover it. Otherwise, that changes will be reverted with that PR.

[se7entyse7en]

This is something that IMO should be discussed company-wide with @src-d/engineering. I don't know how other teams handle this or whether all teams use GitBook, but I'd vote as an easy (I guess) thing to do prevent committing to master. If we want to go on with GitBook as @dpordomingo it worth mentioning the flow on the guide.

Adding label for @src-d/product to decide about this.

\cc @smola

[se7entyse7en]

I'm moving this to backlog for now.