2009/8/11 Jeroen Vermeulen <[email protected]>: > Matthew Revell wrote: > >> I've rewritten the help guide for projects wanting to use LP to >> translate their software and would love your feedback. > > These are pretty small tasks... hope the pages don't become too fragmentary. > But definitely good to give the user pages they can see the bottoms of!
I agree we should be careful not to fragment the help pages but I think each of these can benefit from separate articles, not least so that we can more easily link to specific articles but also to avoid overwhelming people -- or, as you say, to make it so people can see the bottoms of the pages :) >> https://help.launchpad.net/Translations/YourProject/Draft > > I like the Important/Quick tip/Note boxes! Great, I really wanted to something to break up the mass of text. > Missing "about" in this link, I think: "Read more translation licensing." Thanks, fixed. >> https://help.launchpad.net/Translations/YourProject/ImportingTemplates/Draft > > This paragraph, to my mind, needs qualifying: > > "Launchpad can automatically import your translation templates from a Bazaar > branch. Each time you commit a change in your templates to your Bazaar > branch, and then push the branch to Launchpad, Launchpad will update the > strings available for translation in your project." > > This seems to suggest that these imports will happen without any further > configuration. The "Enabling automatic template imports" header later > dispels that, but the first impression has a way of sticking around. I've changed it to: You can choose from two methods of importing translation templates: * recommended: automatic and ongoing imports of your templates, and optionally also translation files, from a Bazaar branch you specify * or manually upload .pot files using the web interface. I think that works better. > I find the "Push the branch to Launchpad" section a bit confusing, simply > because this is all so flexible. I don't have much in the way of > suggestions, except (1) the exact push instruction is shown on the main page > for each branch, and (2) it may be worth saying that there are many choices, > so that the reader isn't left wondering why the text isn't more specific. I take point 1 but I'm not sure I really see the confusion here. I think it's important to provide one most-likely route. I've added a sub-section on importing from external repos though. > Under "Adding and updating templates," first paragraph, committing a file > isn't really all you need to do: you need to push it, too! Might trip up > users not used to DCVS. > Thanks, fixed. > Also, that section mentions "product series." I think that's code-speak and > "release series" would fit better. Also fixed. > Under "Naming template," is it really true that "a template file does not > carry any metadata"? It contains a header, after all. One of the Translations team wrote that part and I simply adapted it :) > I'd say something like: > > "There can be many templates in a project. When a file comes in, Launchpad > needs to figure out which known template it belongs to--or whether it's a > completely new template. It does this based on the template's file path." > Maybe it's not worth introducing the word metadata here, and instead going > on: > > "Every known template in your project has two identifiers: its > "name" is used to show and refer to the template in Launchpad's user > interface. The other is its "translation domain," which is used in > filenames. Launchpad will pick both based on your template file's path." Thanks, I've used that. > Under "Automatic approval," be sure to mention that this topic literally > makes the difference between minutes and days of waiting time. Ah, of course. > Rather than "If the template is to be added," I would say "If this template > is a new one." I also think there must be a better way of wording "no > template entry must exist in Launchpad Translations that does not have a > matching template file in the branch." Something like, "the branch should > still contain a .pot file for each of the already known templates in your > release series." > This part is a bit academic and seems to see things more from our > perspective than from the user's. Instead of "The latter condition is there > to avoid creating new template entries when in reality the existing template > entry was to be renamed," I'd say something more informal and user-oriented > like "That last rule is there so Launchpad can see that the template is > really new, and not an existing template being renamed." Much better. > Under "Manual translation template imports" I'd say "tar archive" rather > than just "archive." > > Also, just above the "Next steps" heading, why should I visit my project's > translations overview page and click the link for the trunk series? Fixed. >> https://help.launchpad.net/Translations/YourProject/ImportingTranslations/Draft >> https://help.launchpad.net/Translations/YourProject/Policies/Draft >> https://help.launchpad.net/Translations/YourProject/ChoosingAGroup/Draft >> https://help.launchpad.net/Translations/YourProject/Exports/Draft >> https://help.launchpad.net/Translations/YourProject/Exports/Draft > > I'll get to these soon. Thanks for doing this! Many thanks. > PS: I see some inconsistency in emdashes... type <compose><dash><dash><dash> > to get the real thing. I'll fix those on my final sweep before publication. -- Matthew Revell - Launchpad.net - free software collaboration and project hosting _______________________________________________ Mailing list: https://launchpad.net/~launchpad-dev Post to : [email protected] Unsubscribe : https://launchpad.net/~launchpad-dev More help : https://help.launchpad.net/ListHelp
