Closed justinfagnani closed 2 years ago
cc @keanulee @arthurevans
I think it'd be good to figure out at least a lightweight way of doing this before 1.0 so we have stable URLs. We can probably just put the .md files in sub folders for now and manually copy folders on new releases.
We are waiting for jp dir with already translated (almost fully) :jp: Japanese documents of lit-html, also LitElement, PWA Starter Kit !
https://lit-html.polymer-jp.org/ https://lit-element.polymer-jp.org/ https://pwa-starter-kit.polymer-jp.org/ https://www.polymer-jp.org/
repo -> https://github.com/Polymer-Japan/lit-html-docs-jp/tree/jp-translate/docs
ping @keanulee @arthurevans @katejeffreys @frankiefu @yuinchien
:bowing_man: Someone attention please !
We don't have enough resources on our team to maintain translations. Even if someone provides a snapshot of translations now, moving forward we can't realistically update them as we release new versions.
@howking This is super cool. As Keanu said, I don't think we're going to be able to handle localized versions of the official docs anytime soon. I think the best thing we can do is figure out a way to highlight community resources like this.
:smile: Thanks for reply ! OK, We'll keep working on translated repos, and happy from somewhere link, even create PRs at localize-dir ready.
@keanulee I don't think our current infrastructure gives us any great way to version the docs. One (somewhat sad) possibility would be to simply upload official versions as, for example, v1.0.0 to app engine, and add a dropdown that lets people switch sites. (So, basically, if you were looking at an old version you'd be looking at v1.0.0-dot-polymer-lit-html.appspot.com).
We could put the list of versions in the latest docs as, say, '/versions.json', so every version could load the same list from a canonical URL.
That seems like a good approach. I think it's even possible to make that work with our own domain (e.g. v1-0-0.lit-html.polymer-project.org), at least if I'm reading this Stack Overflow answer correctly.
Not going to actually try to set up the DNS now, but can revisit this when lit makes a change that requires another site version.
I think a subdirectory makes a lot more sense. Then we can add new versions without mucking with DNS. Can we just namespace all the docs in /v1/
or /1.0
right now?
Discussed this offline and decided that given uncertainty about the direction we're going, it doesn't make sense change the URL structure at this point. Going to drop the priority on this a little bit and defer until after 1.0.
FYI :ear: This is our temp config for Japanese API Document with typedoc-plugin-localize. (working LitElement too!)
Lit.dev now has a version selector and a way to add new versions going forward.
We should be able to preserve docs for each release, and plan for the future with docs in multiple languages. URLs would end up looking like
https://polymer.github.io/lit-html/en/1.0/guide
orhttps://polymer.github.io/lit-html/en/latest/guide
.