← Back to team overview

brewtarget-devs team mailing list archive

Re: A suggestion for better manuals.- Blueprint


Thanks Phillip,

I do think that this could have potential.

For the repository and languages, everything could be done with only one
repo and branches. The reason I suggested otherwise is that branch created
for future modification of a language could get lost in all the language
branch. We could alleviate the difficulties by prefixing every branch per
the locale.

For the translation process,
First I was thinking that there needed to be a golden standard and I
suggest this to be the EN locale (maybe en_gb, en_us, en_ca) but "en" could
be best. All locale should match the structure of the content that is
present in our golden standard. All ideas and modification on the structure
of the content would need to be introduced in the gold standard before a
specific local. All structural changes on the document would also require
the person to send a proposal for change to be discussed on the mailing
list. Then, once the change is merged, locale may follow. It could also be
a good think to place "Locale Owner" that are in charge of supervising
contribution to their locale and maintain the consistency of idea (This
could be hard on locale with fewer people). I also foresee type and small
changes to be changed directly.

I also had other ideas that we could introduced in our manual development
process at the same time. First, we could link the rolling out of a manual
to a release. Having a tag for manuals for a certain release. This would
remove the (new since x.yy) sections. Also it could be interesting to have
a Release Note section in each locale that mention incomplete sections,
things to change and future work on this locale. We could also have a time
before each release were all developers are suggested to work on updating
the manual for the next release. The contributors list could have a section
for the manual's locale + a section for the gold standard contributors.


On 15 February 2015 at 22:04, Philip Lee <rocketman768@xxxxxxxxx> wrote:

> I think this is fantastic. Great work! I am curious: can you explain in a
> little more detail how you envision the translation process? Can we have
> one repo for the documentation, and one branch per language?
> On Sun, Feb 15, 2015 at 2:07 PM, Maxime Lavigne <duguigne@xxxxxxxxx>
> wrote:
>> Hi everyone,
>> I am sending this email since I am not sure how to insert comments in a
>> Blueprint and Launchpad expired my question.
>> As you may know, I made a proposition to move towards another process for
>> editing, contributing and generating user manuals for Brewtarget. More
>> information can be found on the blueprint page :
>> https://blueprints.launchpad.net/brewtarget/+spec/asciidoc-manuals.
>> I now moved forward and tried a test implementation of what the manual
>> could look like if converted to the format I am proposing. In order to put
>> in place this process, I create another repository that will be removed if
>> we move forward with this solution.
>> https://www.gitorious.org/brewtarget-manuals
>> There should be one additional repository inside the Brewtarget project
>> for each language we want our manual to be translated in.
>> You may look at three different output :
>>   * pdf :
>> https://www.gitorious.org/brewtarget-manuals/brewtarget-manuals/raw/386da8a85acdf31278537c6439f3863c2eed05e4:brewtarget.pdf
>>   * epub :
>> https://www.gitorious.org/brewtarget-manuals/brewtarget-manuals/raw/386da8a85acdf31278537c6439f3863c2eed05e4:brewtarget.epub
>>   * html : Download the brewtarget.html file and open it in a browser.
>> For an overview of the content (which is almost exactly the same) go to
>> any page in the book folder.
>> Let's discuss this!
>> Cheers,
>> malavv
>> --
>> Mailing list: https://launchpad.net/~brewtarget-devs
>> Post to     : brewtarget-devs@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~brewtarget-devs
>> More help   : https://help.launchpad.net/ListHelp
> --
> Dr. Philip G. Lee
> www.linkedin.com/in/philipgreggorylee

Follow ups