one summary to rule them all

[Karsten Wade]

We've struggled for the last several releases with multiple release
summaries and overviews, keeping them in sync, and so forth.

Last release, Paul and I swore we would find a way to provide a single,
canonical source for *all* of these.

Today I noticed yet another release summary in the wild that needs
taming, inclusion, or something:

http://fedoraproject.org/wiki/Features/Policy#Enhancements

A release summary is referred to there that can be added to by anyone.
*sigh*

Do we want to invite those people to instead add their enhancements to
canonical summary?  Then cross-link back in to that namespace?

We can use clever [[Include()]] statements that draw only specific
parts, so each 'mirror' of the canonical summary can show the most
appropriate fragment.

Anyone interested in doing this work?  It involves:

* Working out a single canonical location from amongst the several
  - Releases/#/ReleaseSummary
  - Docs/Beats/OverView
  - Press release needs (more lightweight)
  - etc.

* Define a format for that page so that it can be fragmented (if needed)
for different summaries

* Write up a process for jamming all that together

* Publicize/evangelize

- Karsten

[Jonathan Roberts]

Hey :)
> Do we want to invite those people to instead add their enhancements to
> canonical summary?  Then cross-link back in to that namespace?
>
> We can use clever [[Include()]] statements that draw only specific
> parts, so each 'mirror' of the canonical summary can show the most
> appropriate fragment.

Ah I think this is a super cool idea :)
> Anyone interested in doing this work?

I might - next week at any rate.
> It involves:
> Working out a single canonical location from amongst the several
> Releases/#/ReleaseSummary
> Docs/Beats/OverView

Ummm...what's the difference between these two anyway? Is it possible to
put an end to one of them?
> Press release needs (more lightweight)

This is perhaps going to need refinement seperate from the general
"Release Summary" anyway - isn't it?
> Define a format for that page so that it can be fragmented (if needed)
>
> for different summaries
>
> Write up a process for jamming all that together
>
> Publicize/evangelize

All sounds good to me - I'd love to help out some how with this. Also, I
don't know if anybody's noticed, but I thought the KDE people did a
great job with their release stuff and thought we could learn from them
a bit. Nice tour, press releases etc.

Jon

[Karsten Wade]

On Wed, 2008-01-23 at 19:12 +0000, Jonathan Roberts wrote:
> > Anyone interested in doing this work?
>
> I might - next week at any rate.

That's fine, just trying to get ahead on this before we are behind. :)
> > It involves:
> > Working out a single canonical location from amongst the several
> > Releases/#/ReleaseSummary
> > Docs/Beats/OverView
>
> Ummm...what's the difference between these two anyway? Is it possible to
> put an end to one of them?

The OverView is the one that appears in the release notes.

But you have hit the proverbial nail; we want to make them the same
thing, really, to reduce work and increase consistency.
> > Press release needs (more lightweight)
>
> This is perhaps going to need refinement seperate from the general
> "Release Summary" anyway - isn't it?

I was sort-of hoping that we might have an "overview" in the summary
that is good enough as-is for a press release, press kit, etc.

- Karsten

[Jonathan Roberts]

Hey,
> > > Working out a single canonical location from amongst the several
> > > Releases/#/ReleaseSummary
> > > Docs/Beats/OverView
> >
> > Ummm...what's the difference between these two anyway? Is it possible to
> > put an end to one of them?
>
> The OverView is the one that appears in the release notes.
>
> But you have hit the proverbial nail; we want to make them the same
> thing, really, to reduce work and increase consistency.

OK, I've just taken a quick look at this and it seems like the content
in each of these is actually quite different :S While they're covering
the same material, the ReleaseSummary has got more images etc, along
with longer descriptions and more links. If you were wanting to use one
source for the Release Notes as well, would the images and extra links
need stripping out?

I personally feel that it would be better going under the
Release/#/ReleaseSummary as it seems a slightly more logical place to
look for me - but I think where ever it goes is just going to be an
arbitrary decision?
> > > Press release needs (more lightweight)
> >
> > This is perhaps going to need refinement seperate from the general
> > "Release Summary" anyway - isn't it?
>
> I was sort-of hoping that we might have an "overview" in the summary
> that is good enough as-is for a press release, press kit, etc.

I just took a look at some press releases around the net and they all
definitely take a different approach to the ReleaseSummary or the
OverView - maybe this isn't necessarily a bad thing...

Personally, with respect to making an all purpose document that serves
both the press and the community (be it existing Fedora users or
interestesed open source/free software users), I feel that the
ReleaseSummary is perhaps heading in a better direction as it seems more
"engaging" to me.

I may have missed the boat entirely here!

Jon

[Rahul Sundaram]

Jonathan Roberts wrote:
> Hey,
> > > > Working out a single canonical location from amongst the several
> > > > Releases/#/ReleaseSummary
> > > > Docs/Beats/OverView
> > >
> > > Ummm...what's the difference between these two anyway? Is it possible to
> > > put an end to one of them?
> >
> > The OverView is the one that appears in the release notes.
> >
> > But you have hit the proverbial nail; we want to make them the same
> > thing, really, to reduce work and increase consistency.
>
> OK, I've just taken a quick look at this and it seems like the content
> in each of these is actually quite different :S While they're covering
> the same material, the ReleaseSummary has got more images etc, along
> with longer descriptions and more links. If you were wanting to use one
> source for the Release Notes as well, would the images and extra links
> need stripping out?

As the person behind both of these documents, let me note that release 
notes overview was meant to be more technical while the release summary 
was born out of an earlier effort to do press releases via the 
community. Also due to general lack of contributions (even though 
Jonathan Roberts and others did help for Fedora 8), the time taken to 
write a proper release summary was almost an entire night last time and 
that too way later than the release notes string freeze.

We need to decide whether the overview in release notes can be the kind 
of content that release summary currently is. If that is preferred, let 
me know and I will do that from Fedora 9 onwards. I wouldn't mind more 
people helping out either.

Rahul

[John Poelstra]

Karsten 'quaid' Wade said the following on 01/23/2008 10:58 AM Pacific Time:
> We've struggled for the last several releases with multiple release
> summaries and overviews, keeping them in sync, and so forth.
>
> Last release, Paul and I swore we would find a way to provide a single,
> canonical source for *all* of these.
>
> Today I noticed yet another release summary in the wild that needs
> taming, inclusion, or something:
>
> http://fedoraproject.org/wiki/Features/Policy#Enhancements
>
> A release summary is referred to there that can be added to by anyone.
> *sigh*

It sounds like a good conspiracy on the part of the feature wrangler, 
but it I didn't sneak it in.  It was agreed to by FESCo during the 
review of the feature policy for the upcoming Fedora 9 release cycle.  I 
even encouraged people from the docs team to attend that very FESCo 
meeting. :)

I would continue to encourage people from the docs team to attend FESCo 
meeting when features and the feature process are discussed.

John