search

interagent / http-api-design

HTTP API design guide extracted from work on the Heroku Platform API
https://geemus.gitbooks.io/http-api-design/content/en/
Other
13.69k stars 1.07k forks source link

Korean version of the guidelines #27

Closed yoondo closed 8 years ago

yoondo commented 10 years ago

I translated the guidelines to Korean. If you have any plan to support multi-language, please accept this request or suggest better way to contribute. Thanks!

geemus commented 10 years ago

This looks like a great start. I haven't really had much experience trying to help keep multiple language versions of something (and keeping them synced/up to date). Have you worked on similar projects? Do you have any advice on how best to manage things? Thanks!

rstacruz commented 10 years ago

I recommend hosting the Korean version in another repo (perhaps @yoondo/http-api-design-kr), and linking it from the main repo README. This is the sanest way to do this, in my opinion. Things will get out of sync eventually, and keeping them as separate projects make the differences more manageable.

geemus commented 10 years ago

@rstacruz - thanks for chiming in. I definitely agree they are likely to drift (I imagine they already have at this point). I'm not sure how keeping them as separate projects makes that more manageable though, could you explain? I imagine it could make it more clear that there might be drift, but I guess I'm not certain how it would help avoid that drift. Thanks!

rstacruz commented 10 years ago

When you have something in your project's repository, it'd be the maintainer's responsibility to ensure that they're up-to-date. Practical examples of these would be having Sass and Less versions of a CSS library, or having example code around in examples/.

In these cases, whenever there are new releases of the project, it'd be the public's expectation that everything in the repo is up-to-date. That is, the Sass and Less versions mirror each other's behavior, and the code examples all idiomatically use the correct and the latest API.

Consequently, if you were to release a new version, you'd have to ensure that all those derivative files and example files are kept at par with everything else in the project. If they're not updated, they should be removed or kept elsewhere.

In the example above, consider instead if the Sass version was maintained in a separate repository. This frees the author from the responsibility of ensuring that the Sass version is up to date, lest he breaks the integrity of the project as a whole.

(This is mostly my humble opinion, btw—feel free to disagree!)

geemus commented 10 years ago

@rstacruz it is certainly a compelling argument, and I for one would not be able to help out with the korean translation. Perhaps we could at least link to them to raise awareness, even if we can not really say how up to date they are.

@yoondo what do you think?

yoondo commented 10 years ago

The sole purpose of this pull request is to help Korean developers in regards to the language barrier, and it is not such a huge issue that who or where takes responsibility of this. For now, I think updating Korean version only in my repo will be sufficient. When you expand your plan to support multiple languages on your own, please let me know.

geemus commented 10 years ago

@yoondo that makes sense, thank you. Maybe we could add a section at the end of the guide linking to translations and yours could be first in the list? Do you think that would accomplish the purpose of helping people and maybe making it a bit easier to find? Would you be up for a pull request to make that change? Thanks!

bjeanes commented 10 years ago

I think translations should either be forks or files in the repo. But no matter where it is stored, it should probably record the Git SHA of the English version it is based on, so that updaters can diff the english version to see the drift and fix up the translations. This can be acquired via the actual Git repo but it's a bit indirect and unreliable as the versions drift apart in git history and doesn't help if/when versions are published in other forms (e.g. gh-pages).

geemus commented 8 years ago

I think we have this linked already, so not sure how we left this PR behind. It would be great to consider updating to use the gitbook stuff, but I think regardless we can close this for now. Thanks.