documentation
documentation copied to clipboard
bblfsh
Keep only one project documentation URL
Right now project documentation is available from 2 different URLs:
- https://doc.bblf.sh
- https://docs.sourced.tech/babelfish
As of #222, those two version are even out of sync:
- https://doc.bblf.sh/using-babelfish/clients.html#existing-clients (stale)
- https://docs.sourced.tech/babelfish/using-babelfish/clients#existing-clients (updated)
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.
@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:
- as GH pages does not support .htaccess, we might need to put it on S3 (or host an nginx ourselfs)
- build a site-map of all current URLs at https://doc.bblf.sh/*
- generate s3 bucket structure \w re-directs (or nginx conf)
- point https://doc.bblf.sh domain to that s3 bucket (or nginx instance)
- update link in https://github.com/bblfsh/bblfshd GH repo description to a new one
@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!
cc @mcuadros @eiso @campoy, since all of you had some comments about this some time ago.
Implementing the redirection should be easy. But I'd love to see a definitive approach towards documentation as we also have documentation in:
- https://enry.sourced.tech
- https://siva.sourced.tech
- https://engine.sourced.tech (pointing actually to jgit-spark-connector)
- https://bblf.sh
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.
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)
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).
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.
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.
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.
@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
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.
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.