← Back to team overview

brewtarget-devs team mailing list archive

Re: A suggestion for better manuals.- Blueprint



I just created [brewtarget/manual](https://gitorious.org/brewtarget/manual).
I put the COPYRIGHT file defaulting everything to be licensed under the GNU
FDL 1.3. I also added an "FDL" section since the license requires it, but I
don't know anything about the formatting, so please fix any issues with the
license section (just don't change the text itself, since that is

As you know, I am the "integration manager" (I have push permission) for
the other repos in the Brewtarget project. If this is something you are
passionate about and willing to commit to, I am offering you the
integration manager role for this repo. Are you interested?

On Tue, Feb 17, 2015 at 8:18 AM, Maxime Lavigne <duguigne@xxxxxxxxx> wrote:

> 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.
> Cheers!
> 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

Dr. Philip G. Lee