Paul I appreciate the feedback.
I do have a few thoughts on specific ways things might be made better for new beat writers, but I also imagined that if other beat writers engaged in the conversation, better ideas would emerge.
A little shooting from the hip:
1) Seed the beats, especially the untouched beats, with the information available from yum. This can be done programatically, and I would be willing to work on that, but I suspect that there may be a better way, and in any case, the mapping of packages to beats is something that probably needs to be easily editable, and that raises some issues I haven't reconciled.
2) Provide some relatively automatic way for a beat writer to know what has changed within his domain without grazing all 11K packages. I will do this for myself for F11, whether I can do it in a way that is appropriate in a production environment, I'm less sure. (I'm a big fan of really grody hacks).
3) Provide new beat writers with an assigned mentor, preferably someone with at least some familiarity with the beat content, as well, of course, as the process.
I'm pretty sure other beat writers out there have much better ideas but they are keeping their mouths shut. Perhaps I should have waited a few more days. Indeed, with the holiday fast upon us, many of the stateside beat writers are probably already headed off to their turkeys, leaving their laptops alone and lonely over the long weekend. On the other hand, perhaps some will emerge from their tryptophan haze in a talkative mood!
--McD
On Wed, Nov 26, 2008 at 01:27:33PM -0500, John J. McDonough wrote:
Paul I appreciate the feedback.
I do have a few thoughts on specific ways things might be made better for new beat writers, but I also imagined that if other beat writers engaged in the conversation, better ideas would emerge.
A little shooting from the hip:
- Seed the beats, especially the untouched beats, with the information
available from yum. This can be done programatically, and I would be willing to work on that, but I suspect that there may be a better way, and in any case, the mapping of packages to beats is something that probably needs to be easily editable, and that raises some issues I haven't reconciled.
I think there is a better way -- feeding package information to beats is simply not a good one. We had to change a lot of the Amateur Radio beat for that very reason. Simply listing the results of 'yum info' or 'yum search', or producing a listing of changed version numbers, and calling that release notes devalues the process a bit. It would be fine, however, to give people a command they could use to produce that info locally to save space for more relevant and rich content.
- Provide some relatively automatic way for a beat writer to know what
has changed within his domain without grazing all 11K packages. I will do this for myself for F11, whether I can do it in a way that is appropriate in a production environment, I'm less sure. (I'm a big fan of really grody hacks).
The nice thing about fedorapeople.org and our personal wiki pages is we can hand out all the grody hacks we like. (I do that too.) ;-)
- Provide new beat writers with an assigned mentor, preferably someone
with at least some familiarity with the beat content, as well, of course, as the process.
I'm pretty sure other beat writers out there have much better ideas but they are keeping their mouths shut. Perhaps I should have waited a few more days. Indeed, with the holiday fast upon us, many of the stateside beat writers are probably already headed off to their turkeys, leaving their laptops alone and lonely over the long weekend. On the other hand, perhaps some will emerge from their tryptophan haze in a talkative mood!
I intend to be off the keyboard (or at least, working on nothing beyond my own personal development projects) as much of the weekend as I can, so I can come back more energized. I hope you enjoy yours too!
----- Original Message ----- From: "Paul W. Frields" stickster@gmail.com To: fedora-docs-list@redhat.com Sent: Wednesday, November 26, 2008 7:19 PM Subject: Re: Some thoughts on beat writing
I think there is a better way -- feeding package information to beats is simply not a good one. We had to change a lot of the Amateur Radio beat for that very reason. Simply listing the results of 'yum info' or 'yum search', or producing a listing of changed version numbers, and calling that release notes devalues the process a bit.
Oh absolutely. The yum info stuff merely gives the beat writer some view into what's there. Once he recognizes the version change, the beat writer would then go to the project website (also listed in the yum info), review the upstream's release notes (where available), make a judgement as to whether they really needed comment, and then devise the release notes entry.
I do think that the yum info is a good start for the "what's there" page that the release notes might point to. I do think the beat writer should, however, be encouraged to embellish the yum description. But at least it is a start. A nice summary should go into the release notes preceding the changes, but it should be very brief, perhaps one or two sentences.
I did the amateur radio stuff long before I fully understood what was needed in the relnotes, and by the time I figured out how to figure out what changed, we were well into the period where we weren't making big changes to the wiki and I was reluctant to make massive revisions. If I had known you were going to get stuck with that, I would have been more than happy to go do it.
It would be fine, however, to give people a command they could use to produce that info locally to save space for more relevant and rich content.
My aproach was kind of heavy handed, but having written down what is really needed, something that addresses the minimum needed functionality might be more approachable. I'll have to noodle on that. Actually, sqlite3 is a pretty handy piece of software in its own right!
I intend to be off the keyboard (or at least, working on nothing beyond my own personal development projects) as much of the weekend as I can, so I can come back more energized. I hope you enjoy yours too!
Well good for you. You deserve the break. We'll actually be celebrating Thanksgiving Friday -- the kids need to work Thursday. I've actually been toying with the possibility of spending Thursday melting solder to get away from the keyboard addiction myself.
Enjoy your Thanksgiving.
--McD
Mcd -- are you by chance coming to FUDCon in January? Working out a new process and some tools to go with it for F11 beat writing would make a great hackfest. It's also a chance to teach the sub-projects how to support their beat(s).
More below ...
On Wed, Nov 26, 2008 at 07:56:45PM -0500, John J. McDonough wrote:
----- Original Message ----- From: "Paul W. Frields" stickster@gmail.com To: fedora-docs-list@redhat.com Sent: Wednesday, November 26, 2008 7:19 PM Subject: Re: Some thoughts on beat writing
I think there is a better way -- feeding package information to beats is simply not a good one. We had to change a lot of the Amateur Radio beat for that very reason. Simply listing the results of 'yum info' or 'yum search', or producing a listing of changed version numbers, and calling that release notes devalues the process a bit.
Oh absolutely. The yum info stuff merely gives the beat writer some view into what's there. Once he recognizes the version change, the beat writer would then go to the project website (also listed in the yum info), review the upstream's release notes (where available), make a judgement as to whether they really needed comment, and then devise the release notes entry.
I do think that the yum info is a good start for the "what's there" page that the release notes might point to. I do think the beat writer should, however, be encouraged to embellish the yum description. But at least it is a start. A nice summary should go into the release notes preceding the changes, but it should be very brief, perhaps one or two sentences.
So, yes, there is a novel idea here -- a permanent beat page on the wiki that has:
* Commands to use to get more info about packages (yum info, rpm -q --changelog)
* List of packages for that section
* Programmatically generated changes between FN and FN-1
This is similar to the long requested, sometimes provided, and always dubious "list of packages changed for this release." When we do this, it is always a long, long list on a wiki page; it doesn't belong in the notes themselves; it is slightly useful but only so much so.
- Karsten
----- Original Message ----- From: "Karsten Wade" kwade@redhat.com To: fedora-docs-list@redhat.com Sent: Monday, December 08, 2008 2:24 PM Subject: Re: Some thoughts on beat writing
Mcd -- are you by chance coming to FUDCon in January? Working out a new process and some tools to go with it for F11 beat writing would make a great hackfest. It's also a chance to teach the sub-projects how to support their beat(s).
For a minute there I was seriously considering it, even had the wife convinced, but I had the date wrong in my head. I need to be in Lansing on Saturday. There is a remote chance I can get that moved, but I think it may be too late.
Pity, there's an awful lot going on there I would love to be a part of. I would certainly like to participate Friday and Sunday to the extent I can via email, phone, IRC, whatever.
--McD
On Tue, Dec 09, 2008 at 07:36:58AM -0500, John J. McDonough wrote:
Pity, there's an awful lot going on there I would love to be a part of. I would certainly like to participate Friday and Sunday to the extent I can via email, phone, IRC, whatever.
We're talking about audio for the BarCamp sessions right now, so it got me thinking. I'll bring a mic and we can use Docs conference room on talk.fedoraproject.org. Between that and IRC, we can include you and others virtually to work on this stuff.
- Karsten
----- Original Message ----- From: "Karsten Wade" kwade@redhat.com To: fedora-docs-list@redhat.com Sent: Monday, December 08, 2008 2:24 PM Subject: Re: Some thoughts on beat writing
kind of a separate subject so a separate reply ...
This is similar to the long requested, sometimes provided, and always dubious "list of packages changed for this release."
Yes, well, I've made a couple of runs at this. I have one hack that generates a MediaWiki import file containing the yum description and table of versions for a beat. It is kind of a trail of bread crumbs, though, and probably not all that useful to anyone but me.
A slightly less hack-ey, but still somethng of a hack, I did more recently following a thread with Paul, maybe on IRC I can't recall. But I got to wondering whether I could do something that someone else might actually use. Still a bit of a hack but again, given a list of packages in the beat, compares two sqlite files. Thus, a beat writer could keep the primary.sqlite from F10, grab the primary.sqlite from rawhide, and see what has changed. I mentioned this during the last docs meeting, hoping to get some input from others but no joy. I think this, perhaps prettied up somewhat and with substantial guidance, actually gives the beat writer a shot.
The writer is still faced with figuring out what is actualy in the beat, and this is harder than it sounds. An obvious place would be the PackageKit groups, but these are a lot less helpful than you would suspect. There is a lot of room for judgement in assigning a package to a group, and, IMO, many just plain errors. In some cases when you see a package in some odd group you can imagine how someone felt it belonged there. But even in those cases, you would be hard pressed to imagine groups that you should check. And with 11,000 packages, you just glaze over pawing trough package after package.
--McD
On Tue, Dec 09, 2008 at 08:13:02AM -0500, John J. McDonough wrote:
----- Original Message ----- From: "Karsten Wade" kwade@redhat.com To: fedora-docs-list@redhat.com Sent: Monday, December 08, 2008 2:24 PM Subject: Re: Some thoughts on beat writing
kind of a separate subject so a separate reply ...
I just added you to 'gitfedora-doc-utils', which is this:
https://fedorahosted.org/fedora-doc-utils/
That is where we can put any scripts and such that help us get the Docs work done.
This is similar to the long requested, sometimes provided, and always dubious "list of packages changed for this release."
Yes, well, I've made a couple of runs at this. I have one hack that generates a MediaWiki import file containing the yum description and table of versions for a beat. It is kind of a trail of bread crumbs, though, and probably not all that useful to anyone but me.
Not sure, sounds potentially useful. If we can do it without much hassle, let's do it -- _into_a_special_namespace_. We don't want all this to pollute the wiki search. Alternately, we can just publish to a scratch location on docs.fp.org.
A slightly less hack-ey, but still somethng of a hack, I did more recently following a thread with Paul, maybe on IRC I can't recall. But I got to wondering whether I could do something that someone else might actually use. Still a bit of a hack but again, given a list of packages in the beat, compares two sqlite files. Thus, a beat writer could keep the primary.sqlite from F10, grab the primary.sqlite from rawhide, and see what has changed. I mentioned this during the last docs meeting, hoping to get some input from others but no joy. I think this, perhaps prettied up somewhat and with substantial guidance, actually gives the beat writer a shot.
Does this get more information than 'repodiff'? Sorry if you haven't seen this page, more leaking carpenter's roof:
http://fedoraproject.org/wiki/Docs/Beats/PackageChanges
The writer is still faced with figuring out what is actualy in the beat, and this is harder than it sounds. An obvious place would be the PackageKit groups, but these are a lot less helpful than you would suspect. There is a lot of room for judgement in assigning a package to a group, and, IMO, many just plain errors. In some cases when you see a package in some odd group you can imagine how someone felt it belonged there. But even in those cases, you would be hard pressed to imagine groups that you should check. And with 11,000 packages, you just glaze over pawing trough package after package.
There are a few ways we can define the beats. The way I thought of it originally was an association with a sub-project or sub-component of the distro. This way the beat writer is embedded within the team. This puts the onus on the team to keep their writer up to date.
What that does for us here is to distribute the question of what packages should be watched for a beat, versus trying to figure it out for ourselves for N beats.
The problem is getting the various sub-groups to accept and follow this arrangement. So far, it's been a pretty light adoption, but we haven't really pushed it that far. One thing we can do is guarantee zero coverage without an embedded writer; we've done that ad hoc in the past, but then someone who is not the beat writer comes in and helps fill a bit of information. For example, didn't you do that for Databases this time? So, we keep not fully providing the consequences for sub-groups that don't support the beat writing process.
- Karsten
----- Original Message ----- From: "Karsten Wade" kwade@redhat.com To: fedora-docs-list@redhat.com Sent: Tuesday, December 09, 2008 3:18 PM Subject: Re: Some thoughts on beat writing
Not sure, sounds potentially useful. If we can do it without much hassle, let's do it -- _into_a_special_namespace_.
Certainly willing to share, but it is kind of a PITA. What I do is grab the repo data into a MySQL database so I can collect 'N' releases. It's organized differently than the sqlite db, but no reason the sqlite couldn't be used. It's just that I can make manual changes easier with phpMyAdmin than grokking SQL. Then in a separate step I generate a WikiMedia XML import. Actually, I could see this is something that might be useful for some other audiences, but I found it helpful to watch what packages were undergoing revision, and sometimes it is interesting to dig into those changes and find out what were the issues.
Does this get more information than 'repodiff'?
Actually, less than repodiff, and that's the point. It reads a list of packages in your beat and only reports differences in those packages. It isn't all that difficult to pick up changes, the challenge is picking up changes in a handful of specific packages when there are thousands to wade through. And as we get close to release, many, many packages are changed.
--McD
docs@lists.stg.fedoraproject.org
-
John J. McDonough -
Karsten Wade -
Paul W. Frields