search

bblfsh / documentation

Babelfish documentation (GitBook)
https://docs.sourced.tech/babelfish
Creative Commons Attribution Share Alike 4.0 International
41 stars 30 forks source link

Keep only one project documentation URL #223

Open bzz opened 5 years ago

bzz commented 5 years ago

Right now project documentation is available from 2 different URLs:

As of #222, those two version are even out of sync:

Proposal: keep single "source of truth" project documentation URL and apply HTTP re-directs to it from another one.

Simplest solution: keep only https://docs.sourced.tech and add “301 Moved permanently” to all urls under https://doc.bblf.sh/ , pointing to the right place under `https:/docs.sourced.tech/`.

Implementing this would require knowing where https://doc.bblf.sh/ is hosted and getting access to that place to apply re-directs.

bzz commented 5 years ago

@smola do you know where current https://doc.bblf.sh is hosted and have access to it?

Then I'll be happy to check if it's possible to apply re-directs directly from there.

If not, the simplest solution I can see now is:

bzz commented 5 years ago

@smola do you know where current https://doc.bblf.sh is hosted and have access to it?

I figured that current version is hosted on gitbook.io

$ dig doc.bblf.sh

; <<>> DiG 9.8.3-P1 <<>> doc.bblf.sh
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 54351
;; flags: qr rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;doc.bblf.sh.           IN  A

;; ANSWER SECTION:
doc.bblf.sh.        300 IN  CNAME   www.gitbooks.io.
www.gitbooks.io.    3600    IN  CNAME   cdn.gitbook.com.

According to docs, gitbook support of re-directs is very limited and would not work for our case.

So I guess we should go for "simplest solution" listed above.

CC @rporres for review of the suggested approach given the goals from description. If that makes sense - will be happy to file an Infra issue \w further steps, so plz let me know!

smola commented 5 years ago

cc @mcuadros @eiso @campoy, since all of you had some comments about this some time ago.

rporres commented 5 years ago

Implementing the redirection should be easy. But I'd love to see a definitive approach towards documentation as we also have documentation in:

bzz commented 5 years ago

Implementing the redirection should be easy.

👍 awesome, thank you for prompt feedback @rporres !

But I'd love to see a definitive approach towards documentation as we also have documentation

That sounds very reasonable - do you think it would be better to share the concerns in some new shared issue about documentation e.g in src-d/backlog ?

It's very clear now that this particular issue is not about documentation itself, but only about setting up re-directs between 2 existing web sites for bblfsh project.

Given your feedback above I'm going to prepare the URL mapping between old and new sites and open an issue in Infra.

rporres commented 5 years ago

I'm just saying that before setting redirections and stuff, we should give us a few minutes to think how we should do things from now on... I don't want to invest time on doing redirections and fancy stuff for something we're not going to maintain in the future (as it happens with https://github.com/src-d/docs and https://github.com/src-d/docsrv)

smola commented 5 years ago

IMHO those projects URLs should be redirected to gitbooks too and adopt something entirely different for apidocs (see https://github.com/src-d/feature-idea/issues/59).

eiso commented 5 years ago

I believe we're over thinking this. I would keep both URL's but we need to upgrade gitbook on doc.bblf.sh and set it to the master branch. This way it will always be in sync. This way the project site doesn't feel too linked to the company.

rporres commented 5 years ago

I believe we're over thinking this.

Sorry for being a bit direct here. Given the current situation (at least 3 places for documentation) I'd love to see some thinking about this to avoid maintaining stuff we don't want in the future, e.g. maintaining docsrv related docs is giving me some headaches from time to time.

dennwc commented 5 years ago

I agree with @eiso, both URL makes sense since Babelfish is positioned as a separate project, has its own org, etc. So I'd like to keep https://bblf.sh, if possible.

smola commented 5 years ago

@rporres Please, would you mind opening a separate issue for the docsrv URLs? Even if both things are related, they are not the same and might have different solutions or schedules. Or just comment here: https://github.com/src-d/feature-idea/issues/59

rporres commented 5 years ago

Done, @smola https://github.com/src-d/backlog/issues/1337

campoy commented 5 years ago

The broader question here is whether babelfish should be tied to source{d} or not. Currently, it seems like it's a completely open source project that doesn't have much to do with us ... and I think that's intended (I'm missing a bit of historic context here).

The documentation for source{d} projects will be on their corresponding repos, and maybe we could even having somewhere under docs.sourced.tech/open-source/whatever.

We decided that docs.sourced.tech/foo is reserved for foo product, not project. So for the engine you have the product page under sourced.tech/engine and the docs page under docs.sourced.tech/engine.

If we wanted to have the gitbooks documentation for our projects also on the website, I'm OK with this but not following the same location since they have a very different audience. We already have sourced.tech/open-source so having a docs.sourced.tech/open-source as the entry point of all of our projects would seem pretty logical.

If we want to drop the separation between source{d} and babelfish I would definitely recommend looking into integrating bblf.sh into sourced.tech/open-source/bblfsh and its technical documentation move into docs.sourced.tech/open-source/bblfsh.

smola commented 5 years ago

Re: https://github.com/bblfsh/documentation/issues/223#issuecomment-446070514

If the outcome is going to look anything like this, then I'll agree with @rporres about designing the solution and migration path together for every project instead of just for bblf.sh.