Migrating documentation

[Todd Blose]

Hi everyone,

We're in the process of migrating the documentation out of the wiki and
onto the main site. We expect this to be done by the end of the week. If
you have any changes to the wiki, could you hold off making those until
the process is finished?

Thanks!
Todd

[_pants]

Thanks for the heads up, Todd!

@tlevinson, just wanted to reach out to you to thank you again for all the great work you did a while ago to get this started, apologize for the delay in picking it up, and welcome you to continue contributing to documentation and the Lantern community in general!

Thanks again and hope this finds you well.

[Chris Holmes]

Awesome work Todd!

What's the status on translations of the docs? 

Do we have the docs structured for different languages? And will it be possible to put the docs in transifex and have them automatically get on the site?

--
You received this message because you are subscribed to the Google Groups "Lantern Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to lantern-deve...@googlegroups.com.
Visit this group at http://groups.google.com/group/lantern-devel.
For more options, visit https://groups.google.com/d/optout.

[_pa...@getlantern.org]

On Thu, May 15, 2014 at 1:56 PM, Chris Holmes <cho...@bravenewsoftware.org> wrote:

Do we have the docs structured for different languages? And will it be possible to put the docs in transifex and have them automatically get on the site?

Yup, that's part of the requirements Todd and I discussed last week, thanks for asking.

But that reminds me: Todd, do you know how easy it would be to add a Wikipedia-style "This article also available in: <list of languages>" nav in the sidebar using Sphinx? Could be nice if (say) a Chinese-speaking user lands on the English version of a page but then has an obvious way to get to the Chinese version.

[Chris Holmes]

On Thu, May 15, 2014 at 11:07 AM, <_pa...@getlantern.org> wrote:

On Thu, May 15, 2014 at 1:56 PM, Chris Holmes <cho...@bravenewsoftware.org> wrote:

Do we have the docs structured for different languages? And will it be possible to put the docs in transifex and have them automatically get on the site?

Yup, that's part of the requirements Todd and I discussed last week, thanks for asking.

Sweet.

 

But that reminds me: Todd, do you know how easy it would be to add a Wikipedia-style "This article also available in: <list of languages>" nav in the sidebar using Sphinx? Could be nice if (say) a Chinese-speaking user lands on the English version of a page but then has an obvious way to get to the Chinese version.

Couldn't we just use the same top nav language bar that's on the rest of the website? Seems to me that would be sufficient if it worked.

Also, is https://github.com/getlantern/lantern-docs/tree/master/lantern where things live? If it's helpful I could get some arabic translations in to .rst

[Dragana Kaurin]

Hey Lantern!

Two questions:

1.) Is this an update to share with the rest of the hub translation members? If so, _pants, could you repost on the OTFl10n group?

2.) Why is the Lantern documentation a separate project? Don't we need the documentation available in the same languages as the product? 

If so I can join them together, right now nothing has been translated on the documentation because I don't know what to do with it. Can someone fill me in, so I can get working on the translation? 

D. 

Dragana Kaurin 
Child Protection Communications Expert

UNICEF Syria, Damascus 
Cell: +1 (937) 626 3617 
Cell (Syria): +963 (0)934 202 328
E-mail: dkaurin@unicef.org 

--
You received this message because you are subscribed to the Google Groups "Lantern Internationalization" group.
To unsubscribe from this group and stop receiving emails from it, send an email to lantern-i18n...@googlegroups.com.

[Chris Holmes]

On Fri, May 16, 2014 at 1:25 AM, Dragana Kaurin <dragana...@gmail.com> wrote:

Hey Lantern!

Hey Dragana, good to hear from you.

 

Two questions:

1.) Is this an update to share with the rest of the hub translation members? If so, _pants, could you repost on the OTFl10n group?

Once we finish things up it'll definitely be something to share with the other hub members. But I'm not sure we're totally there yet, with the automated process to get it on the website. 

 

2.) Why is the Lantern documentation a separate project? Don't we need the documentation available in the same languages as the product? 

I'm not super sure. I think pants set it up that way, but I forget the reasoning. There is a decent precedent among other projects on transifex to do their docs as a separate project. But I think one reason they may do it is because their docs are quite large. So it's nice to have a docs project with lots of sub-resources for the chapters, etc. Our Lantern docs are actually pretty small, so I think it could be reasonable to just have it as part of the main project. And I see some advantages to that, of making people more aware there's stuff to be done.

If the system is already set up with things in a separate project it may make sense to just go with that. But if the system is still being configured then now could be a good time to consolidate.

[Snyder Pearson]

I think the main reason for having the lantern docs a separate project was because there are several 'lantern projects' (back in the time there were the client, the controller, and the cloud stuff --and littleproxy, depending on how you count; nowadays there are a bunch more: fte, flashlight, and I'm probably forgetting some).

Having lantern-docs as its own git project allows us to include it as a submodule in the other ones, and thus we can know to what exact version of each project does a version of the docs correspond.

[Chris Holmes]

Oh, we're not talking git repos, we're talking transifex projects. https://www.transifex.com/projects/p/lantern-documentation/ instead of just having everything at https://www.transifex.com/projects/p/lantern/

[Todd Blose]

Hi Chris,

Here are the translations I know of right now: https://www.transifex.com/projects/p/lantern-documentation/resources/ The main documentation pages correspond to transifex resources, according to the list specified here: https://github.com/getlantern/lantern-docs/tree/master/lantern/en/user (it appears only a subset have been created so far--I'll go through and create the remaining resources).

Every documentation page will support whatever transifex translation happens to be available, similar to the other pages on the site. You just select whatever language from the top right nav menu and it references the translation for that page, if available and however far along it happens to be. Sphinx  pulls in the transifex translations at the beginning of the build process and generates separate HTML for every document, in each language available; it uses the angular translate module to perform the string substitutions. There's also a sub-directory created in every language we support.

Thanks,
Todd

You received this message because you are subscribed to the Google Groups "Lantern Internationalization" group.
To unsubscribe from this group and stop receiving emails from it, send an email to lantern-i18n...@googlegroups.com.

[Snyder Pearson]

Whoops, sorry for the noise. :)

[Adam Fisk]

Is there any real advantage to having a separate transifex project for docs? I guess in theory they're lower priority than the client and main web site, so having it separated might make it more likely higher priority things are translated first, but I'm not familiar enough with how translators typically interact with the site to really say.

--

--
Adam
pgp A998 2B6E EF1C 373E 723F A813 045D A255 901A FD89

[Chris Holmes]

I think my conclusion for us is no. 

It is a common practice, see like QGIS - https://www.transifex.com/projects/p/QGIS/ and https://www.transifex.com/projects/p/qgis-documentation/

But if you dig in to it they have a huge number of pages of documentation: https://www.transifex.com/projects/p/qgis-documentation/language/fr/

So if they put things in their main repo then people would be overwhelmed.

I think our docs are likely small enough that it won't pollute things too much. 

And I think there's an advantage of having it in the main repo, with being able to use the same language teams we already have, and to have docs be a critical thing.

What we could potentially do to is use lantern-documentation for developer docs, which we hopefully develop more of. And put user docs in our main transifex.

Todd, would it be much work to move the user docs over to the main repo?

[Dragana Kaurin]

Sup, Lantern?

Yeah, guys, it doesn't make any sense to me why we have documentation separate, with different languages than the rest of Lantern. Same goes for Commotion, I keep telling them the same thing but Chris isn't as involved in localization anymore like you guys are. 

We can put these together-- if you are afraid that some strings are more important then others and need special attention to be translated, and that's the reason for the separate projects, we can certainly fix that-- there is a button on the right that allows you to mark the strings as red (very important) and yellow (fairly important). Having said that, I did point out that the tiny button is not super-duper noticeable to the Transifex devs, and we discussed 1.) having the red and yellow strings be highlighted by the whole row, making it more noticeable to translators and 2.) immediately make the red-colored strings pop-up on top of the list of resources, followed by yellow, and regular ones. They said it makes absolute sense from a UX perspective, however it's not on top of their to-do list, so we may have to wait for this development. 

D.

Dragana Kaurin 

[Adam Fisk]

OK cool. Let's just consolidate then unless there are any objections. As a transifex newbie I'd be flying blind a bit, but maybe one of you guys can just fire away and do it?

[Dragana Kaurin]

I can fire away and do it, but I need a go ahead from you. Also I can walk you through the hub if you'd like

Dragana Kaurin 

[Todd Blose]

I'm all for combining them. I'm new to Transifex too, but it makes sense having a single project that contains everything. How are you planning to structure things now? I assume we can have a master Lantern folder that contains a docs project in a folder underneath? Instead of individual strings, is it also possible to prioritize translations by entire documents?

Thanks,
Todd

[Todd Blose]

No problem at all. I also created a task to merge them. If someone else wants to take the lead on it--but I'm happy to do it myself too. Can someone just make sure I have admin access to the main repo? I joined the team already--so whenever you get a chance!

Thanks,
Todd

[Dragana Kaurin]

I'll move the documentation resources to the regular lantern project, since there have been no translations done, it will become available in all 48 languages that are in lantern.

Dragana Kaurin 
Child Protection Communications Expert

UNICEF Syria, Damascus 
Cell: +1 (937) 626 3617 
Cell (Syria): +963 (0)934 202 328
E-mail: dkaurin@unicef.org 

[Adam Fisk]

Great thanks Dragana!!! Todd can you make sure Dragana has admin access (assuming you have admin access =)?

[Todd Blose]

I don't have admin access currently either. Could someone give Dragana and I admin access please?

Thanks,
Todd

[Carson Fisk-Vittori]

It looks like Dragana has admin access, I can invite you Todd - your username on there is just "todd" right?

-Carson

[Todd Blose]

Carson,

Yep, that's right! You should see a request from ~ 11 hours ago when I asked to join too.

Thanks,
Todd

[Carson Fisk-Vittori]

Ok you should be all set now, let me know if not!

- Carson

[Todd Blose]

Hi,

All of the old resources and missing documentation were added to the main Lantern project:

https://www.transifex.com/projects/p/lantern/resources/

Each of the new resources were given a "Documentation" categorization. You can filter the entire list to just user documentation by selecting that category in the "All Categories" drop-down.

I think it's safe to get rid of the old lantern-documentation project now that everything has been consolidated.

Thanks!
Todd

[Ox Cart]

Handy!

Cheers,

Ox

-----------------------------------------------------------------------------------------

"I love people who harness themselves, an ox to a heavy cart,

who pull like water buffalo, with massive patience,

who strain in the mud and the muck to move things forward,

who do what has to be done, again and again."

- Marge Piercy

[Adam Fisk]

Awesome Todd thanks.Let's nuke it!