Suggestion for writing release notes

[Couret Charles-Antoine]

Hi all,
My name is Fedora and I am a French ambassador. Since Fedora 16, I
write the announce in French for the new Fedora release.
The French team, who translate Fedora, found the release notes written
enough, too short and not suitable for public. It's difficult to
translate and understand these documents.
It is more a concatenation of all provided strings without so much flourish.

I think, the releases notes require to many skills in "data processing"
to understand the news in Fedora. For me, it's the official document to
communicate the changelog with the public and actually, it's not
possible with that.

With the French team, we thought to write the release notes in French
and translate that in English for others translation team.
If you are ok to this project, I can write the document before the 17th
September, it's sufficient for others translation in future.

That could be a Publican replacement for the usual Release Notes. I
don't master yet Publican but I am willing to learn.

In short, the idea is to provide the Release Notes for Fedora 18 in a
detail document avoiding the usual phrasing like bellow:
" Desktop - GNOME has been updated to the latest release XX;
- KDE has been updated to the latest release YY;
- Mate has been packaged for the first time in Fedora.."

The original document would be written in French but translated in
English throught Transifex. Of course, we would need English people to
proofread and improve our translation.


You can read my precedent work for that (Fedora 16 and 17) :
https://fedoraproject.org/wiki/User:Renault/Promotion/Fedora_17
https://fedoraproject.org/wiki/User:Renault/Promotion/Fedora_16

It is more detailed, explained and written.Briefly, for a wide
dissemination.

Thank you for giving me your opinion on the subject.
Charles-Antoine Couret — Renault

[Christopher Antila]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 5 September 2012 22:24:31 Couret Charles-Antoine wrote:
>  Hi all,
>  My name is Fedora and I am a French ambassador. Since Fedora 16, I
>  write the announce in French for the new Fedora release.
>  The French team, who translate Fedora, found the release notes written
>  enough, too short and not suitable for public. It's difficult to
>  translate and understand these documents.
>  It is more a concatenation of all provided strings without so much flourish.
>  
>  I think, the releases notes require to many skills in "data processing"
>  to understand the news in Fedora. For me, it's the official document to
>  communicate the changelog with the public and actually, it's not
>  possible with that.
>  
>  With the French team, we thought to write the release notes in French
>  and translate that in English for others translation team.
>  If you are ok to this project, I can write the document before the 17th
>  September, it's sufficient for others translation in future.
>  
>  That could be a Publican replacement for the usual Release Notes. I
>  don't master yet Publican but I am willing to learn.
>  
>  In short, the idea is to provide the Release Notes for Fedora 18 in a
>  detail document avoiding the usual phrasing like bellow:
>  " Desktop - GNOME has been updated to the latest release XX;
>  - KDE has been updated to the latest release YY;
>  - Mate has been packaged for the first time in Fedora.."
>  
>  The original document would be written in French but translated in
>  English throught Transifex. Of course, we would need English people to
>  proofread and improve our translation.
>  
>  
>  You can read my precedent work for that (Fedora 16 and 17) :
>  https://fedoraproject.org/wiki/User:Renault/Promotion/Fedora_17
>  https://fedoraproject.org/wiki/User:Renault/Promotion/Fedora_16
>  
>  It is more detailed, explained and written.Briefly, for a wide
>  dissemination.
>  
>  Thank you for giving me your opinion on the subject.
>  Charles-Antoine Couret — Renault 
Hi Couret:

This is only my opinion, but I think we should collaborate, rather than change languages.

First, thank you for contacting us before writing the Release Notes in French.
I can't speak for other contributors, but I am surprised that short documentation
is more difficult to translate. It makes sense now that I think of it,
because when we write the documentation, we already know what we're thinking,
but when you translate documentation, you don't know what we were thinking.

You could help us learn to write in an easy-to-translate way by giving
some examples of difficult phrases, then showing what we could write instead.
Many of the Release Notes contributors, like myself, are not professional
technical writers. We would certainly appreciate any advice you have.

Second, as I said at the beginning, I think we should collaborate. If we collaborate,
we can expand our community in new ways. The way we currently write documentation
in Fedora (first in English, then translated) is a waste of resources. There
are many talented and engaged contributors, like you, who could help write
our documentation in a non-English language, then translate it to English. There
are also many contributors like myself who are willing and able to translate
from non-English languages, but who are not comfortable writing in them.

What's even more important is that we have an opportunity to encourage cross-
cultural cooperation. Even if the effect is limited to the people who work on
the Release Notes, we should all be thankful we have this chance to work together
to build something for ourselves and our users.

There are many possible technical problems. Does Transifex allow a document to
have multiple source languages? Would we be able to coordinate who will write
about which components? I think we can ignore these for now (see below).

What I Propose:
=======I welcome you, and everybody, to contribute to the Release Notes in your
preferred language. At least for now, please use the existing categories
for the English-language Release Notes:

https://fedoraproject.org/wiki/Docs/Beats

The ideal result is that many of the Beats will be translated into English from
another language (probably mostly French this time), and many of the Beats will
still be translated from English into other languages. We will have multiple
languages on every wiki page, but that's okay. If it's too confusing, we can
choose a better system for future Fedora releases.

For this first time--especially because the Release Notes must be finished
soon--we should still take the English version as the "primary" version for
Transifex. But when we move the English Release Notes to Transifex, you can
copy your original from the wiki. Transifex doesn't need to know that we wrote
some sections in French then translated to English!

The worst result, I think, is that the Release Notes would be written multiple
times, but once for each language, and the wiki pages will be confusing and too
long.


What does everybody think?



Christopher.
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.12 (GNU/Linux)
>
> iQIcBAEBAgAGBQJQR8d7AAoJEGpo1cWDqVnYWScP+QHPQvw9F4IkzCJqaDuj2oup
> w5Ttx1ulmEdBcJT5LKQ1Dog+PABCAvpwZbEmp0ii4NI7CtD9FyBPg4+5TuBJV3TY
> ukOhkSD9Z6hENmdcJRGUui6eUfRPnn8eB0AkSfbxDNaBxAVxnPJzaaLLFJqqQxdH
> yDy4Xjp5lDmpyNdBX2PP35rieiLSxsDFdktx3ZOg1LzGDU+aRIqwDAHqwJKVeFxY
> /HKcHQuY0GVTVm6588xjpdTtOWVNnvqB8owomug2XZOpwvtaRRD0p63CPM/qrUos
> JsXEL/CK13+nHSRGX+9p0jsVH9rR33HeLEzvP+DmPMEYRoiiZmo3wbI/YM1D3+Dp
> e4pXxEwwxVJG1Yx9umHd5nY2iw5MxYjJQ0owKWV/RGPMuMCnMIpoXG/Hj3uV2u1Q
> KudrKFz5u3N6RKoi10ifWNdmuzfdYo40iPi29vHpNLBnrUSJsRNZj7yyebXP7swM
> /Hzn2MttJVWYSjnqEMlF37j5u+zJ3909goIdIbSXU4aaCeydl3Kwx83/gOW/YKqx
> vfNPp0dGBPVcC/8TJWrw/R9vtvDcckJsQsYo0vJbCeTlp+wDwO9L3v0rNkJ2vUjS
> GCddJaMYz/i6FB7rdPVzorCkwFuDFMUCcowW1+VmiU+MGzSY6PZuCBQExHhSp+RJ
> bbKGnMpWaXS6KjuC7oEe
> =SLlb
> -----END PGP SIGNATURE-----

[Couret Charles-Antoine]

Le 05/09/2012 23:43, Christopher Antila a écrit :
>  First, thank you for contacting us before writing the Release Notes in
>  French.
>  I can't speak for other contributors, but I am surprised that short
>  documentation
>  is more difficult to translate. It makes sense now that I think of it,
>  because when we write the documentation, we already know what we're
>  thinking,
>  but when you translate documentation, you don't know what we were
>  thinking. 
Yes, it's that.
And short documentation = less context, it adds an additional difficulty.
>  You could help us learn to write in an easy-to-translate way by giving
>  some examples of difficult phrases, then showing what we could write
>  instead.
>  Many of the Release Notes contributors, like myself, are not professional
>  technical writers. We would certainly appreciate any advice you have. 
I'm not a
translator for a while, I not haveexamples in mind.
But the sentences are not developed enough and it becomes difficult to
understand.
>  Second, as I said at the beginning, I think we should collaborate. If
>  we collaborate,
>  we can expand our community in new ways. The way we currently write
>  documentation
>  in Fedora (first in English, then translated) is a waste of resources.
>  There
>  are many talented and engaged contributors, like you, who could help write
>  our documentation in a non-English language, then translate it to
>  English. There
>  are also many contributors like myself who are willing and able to
>  translate
>  from non-English languages, but who are not comfortable writing in them. 
It's
interesting. I like it.
>  There are many possible technical problems. Does Transifex allow a
>  document to
>  have multiple source languages? Would we be able to coordinate who
>  will write
>  about which components? I think we can ignore these for now (see below). 
Normally,
Transifex can change the reference language.
>  The ideal result is that many of the Beats will be translated into
>  English from
>  another language (probably mostly French this time), and many of the
>  Beats will
>  still be translated from English into other languages. We will have
>  multiple
>  languages on every wiki page, but that's okay. If it's too confusing,
>  we can
>  choose a better system for future Fedora releases. 
For beginning, we can redact a
document with one reference language,
it's easier.
>  For this first time--especially because the Release Notes must be finished
>  soon--we should still take the English version as the "primary"
>  version for
>  Transifex. But when we move the English Release Notes to Transifex,
>  you can
>  copy your original from the wiki. Transifex doesn't need to know that
>  we wrote
>  some sections in French then translated to English! 
Ok.
Thank you for yourcomments.

Charles-Antoine Couret

[Sita-pati das]

I like your promotional notes because they are more top-down and tell the
backstory to the details. Sometimes it's difficult to figure out the story
from the terse details of the release notes.

Short, precise technical details (rel notes) are useful for administrators
and others who are already familiar with the bigger picture (or who are
scanning / grepping / googling for specific version numbers). An overview
narrative like yours provides more context.

What about doing this *in addition* to the current release notes? Maybe we
could have forest *and* trees?


On Thu, Sep 6, 2012 at 6:24 AM, Couret Charles-Antoine
<cacouret(a)wanadoo.fr&gt;wrote:

>  Hi all,
>  My name is Fedora and I am a French ambassador. Since Fedora 16, I
>  write the announce in French for the new Fedora release.
>  The French team, who translate Fedora, found the release notes written
>  enough, too short and not suitable for public. It's difficult to
>  translate and understand these documents.
>  It is more a concatenation of all provided strings without so much
>  flourish.
>
>  I think, the releases notes require to many skills in "data processing"
>  to understand the news in Fedora. For me, it's the official document to
>  communicate the changelog with the public and actually, it's not
>  possible with that.
>
>  With the French team, we thought to write the release notes in French
>  and translate that in English for others translation team.
>  If you are ok to this project, I can write the document before the 17th
>  September, it's sufficient for others translation in future.
>
>  That could be a Publican replacement for the usual Release Notes. I
>  don't master yet Publican but I am willing to learn.
>
>  In short, the idea is to provide the Release Notes for Fedora 18 in a
>  detail document avoiding the usual phrasing like bellow:
>  " Desktop - GNOME has been updated to the latest release XX;
>  - KDE has been updated to the latest release YY;
>  - Mate has been packaged for the first time in Fedora.."
>
>  The original document would be written in French but translated in
>  English throught Transifex. Of course, we would need English people to
>  proofread and improve our translation.
>
>
>  You can read my precedent work for that (Fedora 16 and 17) :
>  https://fedoraproject.org/wiki/User:Renault/Promotion/Fedora_17
>  https://fedoraproject.org/wiki/User:Renault/Promotion/Fedora_16
>
>  It is more detailed, explained and written.Briefly, for a wide
>  dissemination.
>
>  Thank you for giving me your opinion on the subject.
>  Charles-Antoine Couret — Renault
>
>  --
>  docs mailing list
>  docs(a)lists.fedoraproject.org
>  To unsubscribe:
>  https://admin.fedoraproject.org/mailman/listinfo/docs

[Eric Christensen]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 09/05/2012 04:24 PM, Couret Charles-Antoine wrote:
>  I think, the releases notes require to many skills in "data
>  processing" to understand the news in Fedora. For me, it's the
>  official document to communicate the changelog with the public and
>  actually, it's not possible with that. 
I would recommend that if you would like to see more content in the
Release Notes that you write a beat[0].  Many times the short text
that you find in the Release Notes is because no one wrote up more
than that.  If you have additional information to add to the updates
of the desktops or any other beat please add it!

>  With the French team, we thought to write the release notes in
>  French and translate that in English for others translation team. 
>  If you are ok to this project, I can write the document before the
>  17th September, it's sufficient for others translation in future. 
We've done this with one other guide and it generally adds a lot of
time to the document.  This isn't to say that it can't be done but it
needs to be done very quickly.

>  That could be a Publican replacement for the usual Release Notes.
>  I don't master yet Publican but I am willing to learn. 
The Beats are written in the wiki and moved over to Publican so you
won't have to worry about the DocBook XML markup.

>  In short, the idea is to provide the Release Notes for Fedora 18 in
>  a detail document avoiding the usual phrasing like bellow: "
>  Desktop - GNOME has been updated to the latest release XX; - KDE
>  has been updated to the latest release YY; - Mate has been packaged
>  for the first time in Fedora.." 
I agree that it would be nice to have more information in the Release
Notes.  We just need someone to provide that information.

[0] https://fedoraproject.org/wiki/Category:Documentation_beats

- -- Eric
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.12 (GNU/Linux)
> Comment: Using GnuPG with Mozilla - http://www.enigmail.net/
>
> iQIcBAEBAgAGBQJQR+XtAAoJEIB2q94CS7PR+IkQAKI5eqXQtuw1FKxPb/pWyjFi
> nKhTMdZiPabZM+fDdPzsFA3kdnSaRtRBaMEgZ2lu6HbFGZ5LQo1HXOGuor+DF4zx
> vjaomp9ykMHZMAPKRTZFP3psxzjuWbq/V9+a5n/+XGE67ob8Gt8YBZ1JxMydI5xO
> ettJNMNt6hJfVN4kOyBaM+56zJJRgJym31Fu0caEWDZwrWB++qZvvVPU136ZWevO
> FA0Sh5NbEDfqI4alyzvDxYQBB4Nau2CVjEscDNNANsj0+qQJD1ax1P7rrqkyclmj
> 8Pf+FJLIYiDkeBPMZckd3AVohXoWPu2ejjMCMY+83VCQl/FP46Lxxe7tUnm2M+IB
> AWakrTRl8RWBZEboIwns54a1qJDGfOEBaeZ33ZJ7FIYqNiWmOZRVMfF+6k4HORKL
> 2moeTjbCvANov1mZiTMaW8tNhF1N1ZR8LXEuAGkvPhxulzFmSfvLUlWvCWuABCOb
> D1ObZcMSZeKl91xZY2L1Vlrhb/jMdsYmUak38AbFXjoEs8vANzxGltvG5jkRPPlX
> hgIPNfi0sIvu3Yzqn1OWYNNNcgy1xQE8wJH42DlG/aoZh2zFqdoigfsT+yYFtr6f
> hKkA6JQbTG3o6UDQ2BDynWZZSH+mToTKszzMVKYVjemxkau0GXER+0VTd9XcUtEF
> iWxRpydHr6r6wBvqkcGY
> =krQ6
> -----END PGP SIGNATURE-----

[Ben Cotton]

On Wed, Sep 5, 2012 at 4:24 PM, Couret Charles-Antoine
<cacouret(a)wanadoo.fr&gt; wrote:

Bonjour!

Thanks for your suggestion, we're always open to ways we can do things
better. That being said, I'm leary of trying to make major changes to
anything at this stage. I'd rather we took the time to discuss it and
work out potential issues so we can get it right, perhaps with a
target of Fedora 19 for any changes we agree upon.

Here are my quickly-assembled thoughts on the matter. I hope I address
all of your points.

First, I wonder if we're conflating the arguments for the Release
Announcement and the Release Notes. The Release Announcement is a
joint effort between Docs and Marketing and is geared toward media and
general public audiences. It contains mention of key features in the
release in generally non-technical terms. In my mind, the Release
Notes are aimed at an audience that have at least some Linux
knowledge. Not necessarily experts, but at least familiar with the
basics.

I very much agree, however, that "$package was updated to $version" is
insufficient (I'm probably guilty of writing this in some of my
beats). I don't know that the correct solution to this is to
completely change the Release Notes process. I'd rather see more beat
writers so that people can spend more time researching and writing
better sections in the release notes. Certainly, if anyone sees
sub-standard Release Notes entries, they should feel free to contact
the writer for that beat or make changes themselves. Most of the beats
could stand to be more explanatory.

In my experience, Release Notes do tend to be more dry and
technically-oriented. Personally, I prefer something like what we
currently produce so that I can get a quick feel for what has changed
without having to dig through the Technical Notes. I may not be a
representative user.

I'm curious if you've spoken with other translation teams or
ambassador groups about this. Do they feel the same way?


Thanks,
BC

-- 
Ben Cotton
Fedora Docs Leader

[Couret Charles-Antoine]

Le 06/09/2012 05:32, Ben Cotton a écrit :
>  On Wed, Sep 5, 2012 at 4:24 PM, Couret Charles-Antoine
>  <cacouret(a)wanadoo.fr&gt; wrote:
>
>  Bonjour!
>
>  Thanks for your suggestion, we're always open to ways we can do things
>  better. That being said, I'm leary of trying to make major changes to
>  anything at this stage. I'd rather we took the time to discuss it and
>  work out potential issues so we can get it right, perhaps with a
>  target of Fedora 19 for any changes we agree upon. 
Yes, of course, we can elaborate
a redaction for Fedora 19. Fedora 18,
it was just in case.
>  Here are my quickly-assembled thoughts on the matter. I hope I address
>  all of your points. 
It's ok. ;)
>  First, I wonder if we're conflating the arguments for the Release
>  Announcement and the Release Notes. The Release Announcement is a
>  joint effort between Docs and Marketing and is geared toward media and
>  general public audiences. It contains mention of key features in the
>  release in generally non-technical terms. In my mind, the Release
>  Notes are aimed at an audience that have at least some Linux
>  knowledge. Not necessarily experts, but at least familiar with the
>  basics. 
Yes, I understand and I quite agree.
However, I think that classes well separated, we canmake an only
announcement can be read by non-specialists and experts, they will read
the parts that concern.
>  I very much agree, however, that "$package was updated to $version" is
>  insufficient (I'm probably guilty of writing this in some of my
>  beats). I don't know that the correct solution to this is to
>  completely change the Release Notes process. I'd rather see more beat
>  writers so that people can spend more time researching and writing
>  better sections in the release notes. Certainly, if anyone sees
>  sub-standard Release Notes entries, they should feel free to contact
>  the writer for that beat or make changes themselves. Most of the beats
>  could stand to be more explanatory.
>
>  In my experience, Release Notes do tend to be more dry and
>  technically-oriented. Personally, I prefer something like what we
>  currently produce so that I can get a quick feel for what has changed
>  without having to dig through the Technical Notes. I may not be a
>  representative user. 
Ok, I note that.
I am also a developer, system administrator and passionate Fedora. And
the release notes in the state does not really help me to understand
everything that is new and interesting. I do not know if my vision is
more common than you
>  I'm curious if you've spoken with other translation teams or
>  ambassador groups about this. Do they feel the same way? 
All French team of
translation is agree with that. I do not think that
French is so special that it is not shared.
After this is not catastrophic either, but there are difficulties in places.

Thank for your answer.
Charles-Antoine Couret.