Open Stack

On 2017-08-01 18:24,  Ian Y. Choi  wrote:
> Hello,
> 
> Doug Hellmann wrote on 8/2/2017 12:43 AM:
>> [resending to the lists]
>>
>>> On Aug 1, 2017, at 10:55 AM, Doug Hellmann <doug at doughellmann.com
>>> <mailto:doug at doughellmann.com>> wrote:
>>>
>>> Excerpts from Andreas Jaeger's message of 2017-08-01 08:57:09 +0200:
>>>> On 2017-07-31 22:46, Doug Hellmann wrote:
>>>>> Excerpts from Ian Y. Choi's message of 2017-08-01 03:16:09 +0900:
>>>>>> [...]
>>>>>> 2. Draft index page for translated documents was also removed
>>>>>>
>>>>>> Previously, Docs team maintained draft documents for the master
>>>>>> branch 
>>>>>> (which will be the stable branch
>>>>>> after the official release and the document stables) on 
>>>>>> https://docs.openstack.org/draft/draft-index.html page.
>>>>>> It also contained translated draft documents and I18n team
>>>>>> accessed the 
>>>>>> page to see whether translated documents
>>>>>> render well or not, and also review translated strings.
>>>>>>
>>>>>> I did not notice when I saw the spec [1], but recently, I noticed
>>>>>> that 
>>>>>> the the draft-index.html page was deprecated
>>>>>> by [next-release-name]/index.haml (e.g., 
>>>>>> https://docs.openstack.org/pike/index.html ) [4].
>>>>>>
>>>>>> Since I18n team encourages translation review for the better
>>>>>> quality of 
>>>>>> translations, it is a good idea to see
>>>>>> draft documents before language landing pages have the link to fully 
>>>>>> translated and reviewed documents.
>>>>>
>>>>> Is it possible to see the draft of a translation by reviewing the
>>>>> output of the job that proposes the patch containing the translated
>>>>> text?
>>>>
>>>> Currently not, it needs publishing to docs-draft and a way to access the
>>>> multiple documents. Note this needs handling for both openstack-manuals
>>>> and project repos like neutron (networking-guide).
>>>
>>> Could we make it work that way? I understand why we need a separate
>>> review step for the translations, but not why we need a separate
>>> copy of the docs published outside of the context of a job in order
>>> to perform that review. (This is probably just me not understanding
>>> how a tool works.)

We publish as usual - the only difference is the addition of the link.

Since we import translations without review, we want to give teams a
chance to review a complete book before we link to it the first time.
And thus, we built it and publish at the final URL - and only link from
it from our drafts page.

This is not done outside of a job. It's just that we didn't want to wait
for each language team to review a manual, then make changes in
translate.openstack.org, wait for next import, then another team
blocking import etc - and thus never merging anything...

> It would be much nice if the job also supports the publication for
> translated documents,
> assuming that the translated document build work should not interfere
> with the main documentation build steps.
> 
> But for general perspective, if the target of translation is not all of
> documents in openstack-manuals,
> we might need to analyze whether inclusion of translated document build
> jobs is better or not.

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
       HRB 21284 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126