00:00:18 <Sparks> #startmeeting Docs Project Meeting - Agenda: http://fedoraproject.org/wiki/Docs_Project_meetings 00:00:18 <Sparks> #meetingname Fedora Docs 00:00:18 <Sparks> #topic Roll Call 00:00:18 <zodbot> Meeting started Thu Nov 25 00:00:18 2010 UTC. The chair is Sparks. Information about MeetBot at http://wiki.debian.org/MeetBot. 00:00:18 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic. 00:00:18 <zodbot> The meeting name has been set to 'fedora_docs' 00:00:23 * Sparks is here 00:00:35 * jhradilek is here. 00:00:52 * jjmcd 00:02:07 * sgordon is here 00:03:39 <Sparks> #info rudi will not be with us tonight but did pass along some information that I'll bring up a little later. 00:05:16 <Sparks> Okay, lets get started. 00:05:25 <Sparks> #chair jjmcd 00:05:25 <zodbot> Current chairs: Sparks jjmcd 00:05:32 <Sparks> #topic Follow up on last week's action items 00:05:45 <Sparks> #info Completed - Sparks to add creating and publishing links to the Docs wiki page 00:05:59 <Sparks> jjmcd to try to draw more discussion on desktop publication on the list 00:06:11 <jjmcd> Didn't do that 00:06:45 <Sparks> #action jjmcd to try to draw more discussion on desktop publication on the list 00:06:56 <Sparks> #action rudi will update wiki page on publication to desktop 00:07:06 <Sparks> Not sure if rudi got that up yet. 00:07:28 <Sparks> #topic Removing redirects on docs.fp.o 00:07:35 <Sparks> #info When Fedora 13 was released we had just upgraded to the latest version of Publican which changed all of our links on docs.fp.o. The search engines hadn't had enough time to catch up with the new URLs so we added links to act as redirects so the old URLs would still work. 00:08:01 <Sparks> I've found another problem... 00:08:22 <Sparks> #info fedora-bookmarks package contains links that use the redirects 00:09:32 <Sparks> The current redirects still point to the F13 documents. 00:10:14 <jjmcd> Shouldn't the package have been updated for F14 (and tested)? 00:10:36 <Sparks> I don't know 00:11:23 <Sparks> The bigger problem is that these bookmarks are only pulled when the profile is created so updating the bookmarks won't actually fix the problem. 00:12:23 <jjmcd> I guess I don't get where they are. Presumably install can do a update-desktop equivalent 00:12:54 <Sparks> jjmcd: I don't know. 00:13:40 <jjmcd> Are the bookmarks generic (i.e. nb can fix the redirects) or do they specify F13? 00:13:43 <Sparks> I've opened a ticket to have the links updated 00:13:56 <Sparks> The redirects can be updated... 00:14:11 <Sparks> but if you are on F13 then you will now be pointed to the F14 documents 00:14:29 <jjmcd> Probably the best plan. Get the package fixed by the owner then he will know about it for F15 00:15:24 <Sparks> So update the redirects for F14... make sure the links are fixed for F15... phase out the redirects when F14 goes EOS 00:16:02 <jjmcd> Seems like there needs to be some way to apply a fixed package 00:16:46 <jjmcd> Might not be all that straightforward, but basically, we create the menu database when the system is created then make mods when we run yum 00:16:58 <Sparks> It will fix the bookmarks but any existing bookmarks won't be updated 00:17:20 <jjmcd> Why can't an RPM fix the existing bookmarks 00:17:44 <Sparks> because the existing bookmarks are created from whatever is in the default profile 00:18:06 <jjmcd> WHich default profile? 00:18:10 <Sparks> so the RPM fixes the default profile but the profiles aren't reaching back to for the update 00:18:10 <jjmcd> prodile.d? 00:18:17 <Sparks> I don't know, honestly. 00:18:31 <Sparks> I use "default profile" as a variable for a black box. 00:18:38 <jjmcd> hehe 00:18:49 * Gearoid is here, late 00:19:01 <jjmcd> We run essentially programs to modify stuff in postinstall 00:19:02 <Sparks> Gearoid: Welcome 00:19:13 <jjmcd> I saw Zach sneak in, too 00:19:16 <Gearoid> Sparks, thx! 00:19:37 <zoglesby> Me too, and I am confused... Why keep the redirects for so long? 00:19:38 <Sparks> jjmcd: Do you want to follow up on fedora-bookmarks? 00:19:46 <jjmcd> Sparks, sounds like it needs more digging 00:19:58 <Sparks> zoglesby: Because the existing links that are in the wild can't be updated 00:20:57 <Sparks> jjmcd: Want to follow up? 00:21:15 <jjmcd> Yeah, I'll look into it 00:22:01 <Sparks> #action jjmcd to follow up on fedora-bookmarks updates 00:22:08 <Sparks> Okay, anything else on this subject? 00:22:38 * zoglesby will not hold things up... :) 00:22:43 <Sparks> :) 00:22:55 <Sparks> Okay... I'm going to dynamically add two topics here... 00:23:03 <Sparks> #topic New Publican version 00:23:17 <Sparks> rudi> Sparks: Only that Publican 2.4 will be out next week and will include support for creating custom bookmark menus for Desktop docs! 00:23:50 <Sparks> Since rudi couldn't be with us tonight he wanted me to pass along that.^^^ 00:25:09 <jjmcd> so do we need to discuss that on the list, or should we wait until we see "what is in the bill" 00:25:17 <Sparks> I'm sure there will be an announcement on the list about this. 00:25:28 <Sparks> I'd wait 00:26:07 <Sparks> Okay... on to the next topic... 00:26:27 <Sparks> #topic QA 00:26:38 <Sparks> I think zoglesby wanted to discuss QA tonight. 00:27:22 <jjmcd> You seem to have a different agenda ;-) 00:27:23 <zoglesby> Yeah, we all seem to disagree about the best process for this and I wanted to kind of talk it out a bit 00:28:07 <zoglesby> jjmcd: That's my fault I never added this to it... 00:28:14 <Sparks> jjmcd: Yeah, sorry... this was the other dynamic topic 00:28:16 <jjmcd> or publican 00:28:38 <jjmcd> no matter, short agenda otherwise, and I think we all expected this one 00:29:12 <zoglesby> I still think that bugzilla tasks add a level of complexity 00:29:22 <jjmcd> I still haven't heard a process articulated based on BZ that is actually realistic 00:29:24 <Sparks> It adds accountability 00:29:31 <zoglesby> But will that give us the best over site 00:29:43 <jjmcd> I like having the traceability in BZ 00:29:54 <Sparks> jjmcd: QA is built-in to BZ 00:30:23 <Sparks> I've seen other groups use BZ for just this 00:30:27 <jjmcd> But with what has been talked about so far, every step in the development of a document needs to be spaced by at least multiple days 00:30:37 <Sparks> Why? 00:30:43 <jjmcd> For release notes, we would be too late to start F15 00:30:50 <Sparks> why? 00:31:00 <zoglesby> But then as a doc write to you submit a ticket to yourself with a patch so it can be looked at by QA? 00:31:07 <jjmcd> Because until you do the commit, you really can't move on without the risk of lots of conflicting edits 00:31:12 <Sparks> zoglesby: Sure, why not? 00:31:23 <jjmcd> ANd you are suggesting probably a week between the edit and the commit, if you're lucky 00:31:26 <Sparks> It allows not only for accountability but also as a task list 00:31:35 <Sparks> jjmcd: Again... WHY? 00:31:42 <jjmcd> It removes accountability, adds the task list tho 00:31:43 <Sparks> If I write something now... 00:31:48 <jjmcd> Because you haven't made the commit 00:31:58 <jjmcd> Are you going to MANUALLY do what git does 00:31:59 <Sparks> and add a ticket... 00:32:08 <jjmcd> once you have more than one patch in BZ you're screwed 00:32:14 <Sparks> git can build your diff for you 00:32:14 <zoglesby> jjmcd: I also think that for some guides this can be done a little diff 00:32:21 <jjmcd> Commit, then maybe add the patch 00:32:26 <Sparks> and git will save that commit for later 00:32:44 <jjmcd> Commit now, commit early, commit often 00:33:02 <jjmcd> And what about the poor QA guy? Have you thought through this? 00:33:13 <zoglesby> A guide that is completely changed each release is going to need look at different then something that only needs some parts checked 00:33:16 <Sparks> How are you going to keep non-QA'd documentation from being published? 00:33:23 <jjmcd> TAGS 00:33:30 <jjmcd> Simply publish from the tags 00:33:35 <Sparks> Does that work in SVN? 00:33:41 <jjmcd> Pretty damn simple, and almost no extra work 00:33:54 <jjmcd> In SVN, tagging is more complex, kinda. 00:34:02 <jjmcd> Not really more complex byt risky 00:34:12 <Sparks> How can someone in QA check to see what needs to be looked at? 00:34:23 <jjmcd> Duh? 00:34:37 <Sparks> Quickly 00:34:38 <zoglesby> The commit log 00:34:45 <jjmcd> Or gitweb 00:34:50 <jjmcd> or git checkout 00:35:01 <Sparks> Using BZ I can pull up a list of everything in Docs that needs to be reviewed... in seconds 00:35:19 <jjmcd> How does someone figure out how to create the doc he wants to QA from a random set of patches? 00:35:37 <jjmcd> He must apply all to check one 00:35:41 <Sparks> No 00:36:03 <Sparks> You write a chapter/section... you submit that for QA 00:36:11 <Sparks> move to the next chapter/section 00:36:28 <Sparks> if the QA folks get right on it you could have same day service 00:36:31 <jjmcd> So, only one person working on a doc at a time. IN that edge case, BZ might work 00:36:41 <Sparks> and you'll get an email that tells you when they are done 00:36:44 <jjmcd> COnsider - and this happens all the time in RNs 00:36:50 <Sparks> Why just one? 00:37:08 <jjmcd> THINK THROUGH IT - why do you think we have RCSs in the first place? 00:37:09 <Sparks> Why can't you be working on one section and I working on another section? 00:37:18 <jjmcd> And why do you want to manage that manuclaly? 00:37:18 <Sparks> Clearly we aren't working on the same sentence at the same time 00:37:24 <jjmcd> WHen you have a great tool for it? 00:37:33 <Sparks> We don't 00:37:45 <jjmcd> We do, it's called git 00:37:51 <Sparks> We aren't all using git 00:38:09 <jjmcd> Most are, and SVN is the same damn thing except a little more lame 00:38:10 <Sparks> and I have yet to see where git will easily show what needs to be QAd among ALL the docs 00:38:21 <jjmcd> Only one doc at a time 00:38:27 <Sparks> You are adding a lot of work to the QA folks... 00:38:36 <Sparks> they now have to check two dozen git repos 00:38:36 <jjmcd> NO, I'm removing work 00:38:43 <jjmcd> Think abouit what the reviewer has to do 00:38:46 <Sparks> just to see if there is anything they need to do 00:39:01 <jhradilek> Sparks: You can always file a bug requesting the QA folks to review the selected portion of the book. 00:39:16 <Sparks> they log into BZ... pick up a ticket... read the patch and review... change the status of the ticket... move on 00:39:36 <jjmcd> read the patch? Come on. 00:39:44 <jjmcd> THey need to produce the doc to see the result 00:39:55 <jjmcd> In many cases the patch makes little sense by itself 00:39:57 <Sparks> Why? Aren't you working with source? 00:40:03 <jjmcd> UNless you are intimate with th ebook 00:40:32 <jjmcd> Not all patches are entire chapters 00:40:40 <jjmcd> Most are one liners 00:40:44 <Sparks> Just because you aren't familiar with the SG doesn't mean you can't check the encryption procedures to make sure they work 00:41:00 <Sparks> Yes, one liners would be problematic 00:41:25 <jjmcd> Quite often someone goes back and proofreads and makes a lot of small changes 00:41:37 <Sparks> But handing someone the entire guide and saying "I made a change in there somewhere" isn't a good solution 00:41:41 <jjmcd> ANd worse, quite often several people proofread and make a lot of small changes 00:41:58 <jjmcd> By trying to manually do the revision control you are setting yourself up 00:42:12 <zoglesby> Sparks: But it's I made a change look at the log to see the changes 00:42:39 <zoglesby> And it will point out what lines changed just like a patch 00:42:42 <Sparks> How many changes are you going to do while the section is in QA? 00:43:08 <jjmcd> Sparks, lots 00:43:29 <jjmcd> Unless you want to wait to do QA until you're ready to publish and then the QA becomes a big delay 00:43:57 <Sparks> zoglesby: Hey, it is up to you. I'm not saying "do it like this"... I just want to make sure that the procedure is simple, ensures accountability, and nothing gets left behind 00:44:12 <Sparks> jjmcd: You shouldn't be making changes to the section that is in QA 00:44:18 <jjmcd> http://fpaste.org/73OF/ 00:44:25 <jjmcd> A patch from release notes 00:44:31 <Sparks> If you think something is ready to be published then it is ready for QA 00:44:34 <jjmcd> How is a reviewer going to tell what that means 00:45:00 <zoglesby> Indeed and I think that some exceptions will need to be no matter what we go with 00:45:10 <jjmcd> So we slide our schedules up a couple weeks? 00:45:23 <Sparks> jjmcd: Ummm... you removed systemd 00:45:26 <jjmcd> Certainly wouldn't work for release notes. we barely have enough time as it is 00:45:49 <Sparks> jjmcd: We have to get the RNs under control 00:46:11 <Sparks> That's a different topic but you and I both agree that these late coming RN emergencies is not the way to go 00:46:12 <zoglesby> jjmcd: RNs are special, it's a complete rewrite every time 00:46:22 <jjmcd> Problem is, what we write about isn't stable until a few weeks before release 00:46:29 <jjmcd> if then 00:46:41 <zoglesby> I am going to have to spend a good deal of time once you starting pushing to repo to QA it 00:46:46 <jjmcd> Sometimes, like this release, FESCo makes big changes at the last minute 00:47:35 <jjmcd> Yes, the RNs are a little different, more because a lot of people work on them 00:47:48 <jjmcd> So revision control is critical and can't be left to chance 00:48:13 <Sparks> Okay, we can't hash this out here all night. 00:48:24 <Sparks> zoglesby: I'm leaving it up to you to come up with a solution that will work. 00:48:25 <jjmcd> But I just can't imagine why someone would want to keep their workhidden until the last minute 00:48:38 <Sparks> jjmcd: Nothing is hidden on BZ 00:48:47 <zoglesby> Indeed, I will work on it 00:49:02 * Sparks thinks work in the repos are more hidden from public eyes 00:49:03 <jjmcd> No, but you are suggsesting everything stays hidden until you submit the qa request 00:49:16 <jjmcd> I think if you leave edits uncommitted overnight you are making a mistake 00:49:22 <zoglesby> And reengaged on the list 00:49:31 <Sparks> jjmcd: Good point. 00:49:37 <Sparks> Okay... moving on 00:49:38 <jjmcd> Now, when you have some monstrosity like CVS I can see the reluctance 00:49:58 <zoglesby> I tend to agree with jjmcd it's just finding a working process to go with it 00:50:13 <jjmcd> ANd I don't think a reviewer can review just the patch, especially with the guides 00:50:24 <Sparks> zoglesby: Up to you. Just make it happen and get some folks up and running. 00:51:00 <Sparks> We'll need to get procedures up on the wiki asap 00:51:01 <zoglesby> Ok, thats all I had about that 00:51:19 <Sparks> #topic Publishing Documentation to the desktop 00:51:34 <Sparks> I don't have anything else on this... we'll come back to this next week. 00:51:37 <jjmcd> Didn't we just say let's see 2n4? 00:51:41 <jjmcd> yeah 00:51:50 <Sparks> Yes 00:51:59 <Sparks> #topic Guide Status 00:52:44 <Sparks> Anyone have anything they need to discuss about guides/ 00:52:46 <Sparks> ? 00:53:02 <jjmcd> You saw I added some xastir stuff to ARG, that app has a zillion features tho 00:53:09 <Sparks> Yes 00:53:12 <jjmcd> And the six or so pages aren't near enough 00:53:22 <Sparks> I was going to work on that but I just need some time! 00:53:36 <jjmcd> We all have that prob 00:53:37 <Sparks> jjmcd: Probably just going through the basics is all that's needed 00:53:54 <jjmcd> Nothing there on setting up an igate tho 00:54:11 <Sparks> I can do that 00:54:57 <Sparks> Anything else? 00:55:07 <jjmcd> I had some weather today so I was able to get screen caps 00:55:28 <jjmcd> but I wasn't thinking about the doc when I grabbed them so I'm not so sure they will be appropriate 00:55:59 * Sparks needs to talk with jjmcd about grabbing screen shots 00:56:26 <jjmcd> still multiple steps :-( 00:56:40 <Sparks> :/ 00:56:41 <jjmcd> Grab the png, convert, then adjust for the pdf 00:56:55 <Sparks> procedure on the wiki? 00:57:00 <jjmcd> naw 00:57:10 <jjmcd> rudi was going to do something about the convert 00:57:16 <jjmcd> in the log from a couple weeks ago 00:57:27 <jjmcd> but the adjusting for the pdf is a multiple step thing 00:57:54 <jjmcd> html and pdf have different requirements so it is a bit of a game to balance them 00:57:55 <Sparks> It would be good if we could get something up on the wiki 00:58:40 <jjmcd> Why? Then it wouldn't be a secret anymore 00:58:50 <Sparks> heh 00:58:52 <zoglesby> lol 00:59:04 <Sparks> #topic Open floor discussion 00:59:12 <Sparks> Okay, anyone have anything else? 00:59:44 <jjmcd> I did, but I forgot 00:59:48 <Sparks> heh 01:00:01 <jjmcd> Happy Thanksgiving 01:00:10 <jjmcd> Eat lots of dead bird flesh 01:00:19 <zoglesby> Who do I ping to get the docs-QA list made? 01:00:19 <Sparks> Oh... I should pass along rudi's other comment 01:00:28 <Sparks> zoglesby: Open a ticket with Infra 01:00:40 <Sparks> <rudi> Sparks: and Happy Thanksgiving to everyone States-side, except, inevitably, the turkeys 01:00:58 <Sparks> anyone/anything else? 01:01:15 <jjmcd> Wow, that hour went fast 01:01:33 <Sparks> Okay, discussions to continue on the list. 01:01:43 <Sparks> Thanks everyone! 01:01:51 <jhradilek> Thank you. :) 01:02:02 <Sparks> #endmeeting