00:00:24 #startmeeting 00:00:24 Meeting started Wed Apr 16 00:00:24 2014 UTC. The chair is paulz. Information about MeetBot at http://wiki.debian.org/MeetBot. 00:00:24 Useful Commands: #action #agreed #help #info #idea #link #topic. 00:00:36 Still waiting for folks, obviously 00:01:21 Meeting agenda is here 00:01:25 #link https://wiki.opendaylight.org/view/CrossProject:Documentation_Group:Meetings#Tue.2C_4.2F15.2C_5:00_PM_.28USA_Pacific.29 00:01:57 is there a webex too ? 00:02:28 No, just IRC... although I'm thinking we might want to start doing meets by WebEx... this can be kind of slow sometimes. 00:03:04 thanks for the agenda Paul 00:03:29 yeah .. specially during startup phase, good for new folks like myself 00:03:55 OK, let's make the next one a combo WebEx/IRC. I'll set it up. 00:04:18 #idea Have our meets by WebEx as well so that we can address issues more quickly. 00:04:21 thx 00:04:27 im here 00:04:33 #action paulz to set up a WebEx for next time 00:04:37 Hi Andrew! 00:05:03 sry i was afk last meeting, webex would be good too 00:05:46 ok 00:06:40 Well, 6 min in, I guess we can get rolling, still hoping more folks show up 00:07:04 #topic Actions from Last Meeting 00:07:23 The first one is Mathieu to verify Andrew's server requirements work with ODL doc toolchain 00:07:48 i never had a chance to sync up, sry on that 00:07:55 Hi Paulz, spoke with Andrew, still don't have the answer on that one.. 00:08:07 please keep it pending item 00:08:15 (lump it in infrastructure plz) 00:08:20 Sry, Andrew Kim... this is Andrew Grimberg from Linux Foundation 00:08:21 mlemay, is this for me or a different Andrew 00:08:24 ah okay 00:08:31 OK, will do! 00:08:33 different Andrew ;) 00:08:36 tykeal 00:08:44 #action Mathieu to verify Andrew's server requirements work with ODL doc toolchain 00:09:03 Next is gjs to sync with mlemay on doc cleanup 00:09:25 Hi, I got the changes commited to my repository and sent it to Mathieu this afternoon 00:09:26 actually it's really about the output.. I can use site-deploy but not 100% sure the output is what we want... lets see.. I'll get it going 00:09:35 yup 00:10:04 looked at gjs's work quickly before the meeting and all looks ok.. thanks alot.. I'll run the conversion on it sometime this week 00:10:20 Let me know after you run it if you need additioal changes. 00:10:35 ok +1 00:11:58 Alright, we're moving right along here... next one is mlemay to convert guides to asciidoc... 00:13:26 right that is dependent on previous item.. ;) 00:13:33 didn't get a chance just yet 00:13:58 Gotcha... OK, we'll carry that one... 00:14:07 #action mlemay to convert guides to asciidoc 00:14:11 perfect 00:14:19 will be done for next meet 00:14:30 Next is paulz to create wiki page to collect ideas for index page 00:14:53 I did that here 00:14:56 #link https://wiki.opendaylight.org/view/CrossProject:Documentation_Group:Content_Ownership 00:15:14 Just did it today, though... so no one has been able to review yet! 00:15:29 Oh, sorry, that's not for the index page 00:15:39 OK, that one will have to carry as well 00:16:05 #action paulz to create wiki page to collect ideas for index page 00:16:13 I'll get that done shortly 00:16:35 no worries 00:16:42 we just got incumbated! 00:16:43 Which means the next one carries as well... team to review index page ideas by next meeting 00:16:47 *incubated 00:16:49 #action team to review index page ideas by next meeting 00:16:55 BTW congrats to all 00:16:55 :-) 00:17:37 Yeah, that's really good!! We got past a major milestone. 00:17:40 Paulz.. you might've missed the item on the TSC call if you didn't stay till the end but there was a priority request that was raised to our group 00:17:52 it's to establish and propose documentation guidelines for projects 00:18:06 (as soon as possible) 00:18:25 Oh, I didn't stay to the end... OK... that fits into our charter... we'll make that part of our ongoing agenda. 00:18:54 #action Add "establish and propose ODL documentation guidelines" to our agenda 00:19:23 thanks 00:20:40 So in addition to our idea collection for an index page, we should also have an idea collection page for doc guidelines. I see having standard doc types and consistent processes as key items. 00:20:50 yes 00:21:10 also they want us to provide maven templates for the project sites etc.. 00:21:27 but first the guidelines (what should be provided as docs by a project) 00:22:06 OK, great... sounds like we can prioritize that, as we can have guidelines before the toolchain is fully operational. 00:22:34 #action paulz to create an idea collection page for doc guidelines 00:22:39 I'll get that done this week 00:23:19 perfect 00:23:26 we can then bring that back to TSC 00:23:30 for discussion 00:24:15 Hi Rob 00:24:28 Hi all; sorry I'm late; three-week check-up for the baby. 00:24:36 Hope all is well!! 00:24:36 no worries 00:24:38 congrats again 00:25:08 Thanks much. He's up from 8 lbs 3 oz at birth to 10 lbs 5 oz; so far, so good (except for sleep ) 00:25:37 That's what coffee is for! 00:26:00 Yes; and chocolate :) 00:26:13 Alright, one last action from last time... paulz to have Content ownership and design docs/templates on the agenda for next time... done. 00:26:13 hahaha 00:26:46 Any other comments or questions on Actions from Last Time? 00:27:26 OK, I'll take that as no... 00:27:32 #topic Project Status 00:27:36 no 00:27:47 (little delay) 00:27:53 #info The OpenDaylight TSC approved our proposal last week 00:28:03 I'm typing too quickly... we definitely need the WebEx... that will help! 00:28:07 Go Docs Team ! :) 00:28:49 Yes!! It was a very good moment... now we gotta work! 00:28:54 :-) 00:29:18 It looks like there are three items on the project status agenda: 00:29:22 a) Toolchan setup 00:29:27 b) Content ownership 00:29:33 c) Design docs / templates 00:29:41 Yep... onto Toolchain 00:29:47 #topic Toolchain Setup 00:30:34 on that... Any other feedback on initial runs for the manuals? If ok for now we should quickly cover site-deploys (for proojects) 00:30:43 based off some of what Ryan (regXboi) did 00:32:00 Greg and I have been getting feedback to work on MD-SAL, but yeah, maybe site deploys would be a good way to ensure that we have the tooling all working correctly before we dive into the bigger topics... 00:32:01 Do we know how many peole have gone through the toolchain set-up? I know I'm behind and haven't had a chance yet. 00:32:13 Rob, it's not 100% yet6 00:32:31 But its close! 00:33:00 #info Discussion of which areas to start documenting. 00:33:05 +1 on that.. right now was docbkx.. I did asciidoc support 00:33:13 last week 00:33:29 so now the focus should be on site-deploy, javadoc and general reporting 00:33:40 then we can link all that together) 00:33:44 (IMO) 00:34:35 what we need is some "parent pom-ish" way to help projects in this regards... right now it has been very difficult for them 00:35:10 (it relates to the checklist / recommended doc ) but really a step towards continuous documentation 00:35:52 That sounds good to me. we covered some of the needed tasks in the actions earlier... Mathieu & Greg, any other actions needed at this point? 00:36:45 I don’t know enough about out all this to tell you what’s next. But I’m willing to pitch in with the drudge work. 00:37:26 ok Greg.. if you wish we can touch base next Tuesday 00:37:35 sadly I'm a little overbooked till then 00:37:51 (with the Easter weekend and all) 00:38:14 No prob. Let me know when you need something from me 00:38:48 thanks alot... I can also work with Ryan, Brent (OVSDB) or other projects if we want to give toolchain for projects a try 00:38:55 one question to the team... 00:39:16 Do we want projects to host their "project related guides" or do we host them in our repository 00:39:50 Also Paul, for my question its to get the proper "docs" repo created now that the project is incubated 00:40:22 (IRC hiccup) 00:40:48 On @mlemay's question about projects doing own docs vs. in central repo, I'm thinking ideally would be central repo 00:41:13 thanks Rob 00:41:17 We would want to be very liberal about accepting new committers to the documentation project. 00:41:27 I agree with Rob. I can work with Andrew G. to get the repository set up. 00:41:37 right it is easier to curate the chapters and compose the guides this way 00:41:56 how about the project-specific sites, javadoc and such? 00:42:03 #action paulz to work with ODL support to get docs repository set up. 00:42:06 If a project is part of one of the OpenDaylight releases (Base, Virtualization, Service Provider, ...) the project should include their documentation in the documentation project. 00:42:47 @mlemay Could you elaborate on what you mean by "project-specific sites" 00:43:19 Right.. however this concept of "distribution" is somewhat changing a bit... some of us have been porting to Karaf container so each project is an runtime installable feature... we can have the same distributions but it's not as difficult/mandatory as it was for hydrogen 00:43:42 @Rob their "mvn site-deploy" 00:43:49 is what I meant 00:44:00 right now projects generate site-deploy artifacts.. 00:44:26 for example OpenDOVE did theirs.. this way the API is versioned , documented... and generated 00:44:47 Ah, I see. 00:44:50 what I was planning to potentially do is generate nice-looking version from the generated "WADL" file 00:45:04 (for the API) 00:45:18 @MLemay, I think you have the best sense of the tool chain. What do you recommend? 00:45:18 but some where thinking about using the maven sites directly 00:45:38 @Rob.. depends what we want it to look like 00:46:06 Personally I think we should have two levels of documentation, USer facing / Developer Facing 00:46:45 IMHO I think user facing should be under our control (docs project) and Developer facing should be provided by our toolchain to projects and generated from their builds 00:46:50 would that make sense? 00:47:04 +1 00:47:14 +1 00:47:23 ++ 00:47:35 +1 00:47:38 +1 00:47:56 ok 00:48:14 lets give it a try this way and if we find it doesn't work we can always change things 00:48:22 Makes sense. 00:48:54 Any other comments/questions on toolchain? 00:48:55 and we should state that in documentation guildelines 00:49:05 #agreed we should have two levels of documentation: User-Facing and Developer-Facing. User-facing should be under our control (docs project) and Developer-facing should be provided by our toolchain to projects and generated from their builds 00:49:47 Thanks, Rob! 00:49:53 :) 00:50:13 getting there.. :) 00:51:03 Per @mrajvaid's comment, would someone want to take an action to start drafting documentation guidelines? 00:51:32 I will create the page to collect ideas (already an action)... 00:51:53 I'm happy to start putting some ideas down 00:52:41 #action paulz Create a page to collect guidelines ideas (may already be an action) and start putting some ideas down 00:52:45 I'll try to put some things there.. but bear with me I'm a little overbooked till our next meeting 00:53:28 Thanks! 00:54:00 #link https://wiki.opendaylight.org/view/HydrogenRelease:Documentation_Scope_and_Location <- Some links to Hydrogen docs 00:54:16 Great... thanks, Rob! 00:54:53 The last two topics on our agenda are probably a little premature, but we can hit 'em quickly... 00:55:01 shoot 00:55:28 Would one of the #chair(s) want to change the #topic ? 00:55:32 #topic Content Ownership 00:55:41 I did a page on this 00:56:00 #link https://wiki.opendaylight.org/view/CrossProject:Documentation_Group:Content_Ownership 00:56:23 but yeah, probably a little premature... 00:56:28 @paulz This is impressive! 00:56:38 Thanks! :-) 00:56:44 nice 00:56:56 great start 00:57:10 We'll work with it as our tools come available and we prioritize content 00:57:36 can you also put me on stylesheets plz.. easier to maintain that plugin if changes are required 00:57:46 is there a timeline for all of this? i suppose by helium release (summer) 00:57:47 #link https://wiki.opendaylight.org/view/Release/Hydrogen <- Links to many legacy docs in the "scratch" section 00:57:54 Makes sense! 00:58:04 Thanks, Rob... I'll get those on the list 00:58:29 #action paulz to look at legacy list and include them in Content Ownership page 00:58:36 #action mlemay Volunteers to work on stylesheets 00:58:45 Also for the manuals you can add something on "guides" if possible.. I'd like to have two sections if you are ok.. HOWTOs and Manuals/Guides 00:59:47 Are you seeing the HOWTOs as shorter tutorials and the Manual/Guides as more comprehensive? 00:59:52 yes 01:00:02 Will do 01:00:16 HOWTO is tutorials.. (we can call them tutorials) for exaample I drafted HOWTO - ODL + OpenStack 01:00:23 (using OVSDB) 01:00:31 based off Madhu/Brent's work 01:00:49 that is a sample HOWTO/Tutorial-ish guide we should have a bunch more 01:01:19 for Guide they are the typical user / developer reference guides 01:01:25 I like the idea of having the HowTos / Tutorials, but there may be a risk to scope creep and a cost to maintain from release to release. 01:01:28 OK, I had line items for "tutorials" but it sounds like we need to be more specific. 01:02:00 Hmmm... maybe that kind of content should stay in wiki format so folks can add at will? 01:02:17 Having these separate from the core manual / documentation might be a good way to minimize "sustaining" work if there's no longer interest in maintaining a HowTo / Tutorial. 01:02:27 @Rob, agreed but problem is people don't really know what to do with ODL once they have it installed 01:02:42 @mlemay Truth :) 01:02:52 If I look at OpenStack it's what gave it traction 01:03:13 The "Operation Guide" was definitely the biggest requirement 01:03:18 for them 01:03:26 (not that it's the same for us) 01:03:36 @mlemay We should chat about what gave OpenStack traction over a drink sometime ;) 01:04:05 @paul : not too sure about wiki format.. lots of people don't like that either.. depends how "official" it is IMO .. I don't think you want a tutorial / howto for everything 01:04:27 I agree that having HowTo / Tutorial content is goodness. I think @ColinDixon (IBM) was also interestedin this. 01:04:27 Good point. We can be selective. 01:04:39 @Rob... hahahah I do have my views :S (which is why I said we are not OpenStack) 01:04:56 but not for everythign IMHO 01:05:31 only essential topics (with a certain degree of traction) should be covered I guess if you guys are ok with this 01:05:55 @Rob... I won't forget the drink :P 01:06:05 :) 01:06:13 Yeah, I'm good with that strategy. 01:06:35 Well, we've gone over time... I'm happy to keep this going, but folks might need to drop... the last topic on our list was something that can be tabled til next time anyway. 01:06:37 My inclination is to err on the side of inclusion, so if @mlemay (or anyone else) wants to draft content, that's goodness. 01:07:00 ok 01:07:03 Yes, agreed... we need contributors for sure, so write away!! 01:07:26 is there a timeline for the base controller listed on https://wiki.opendaylight.org/view/CrossProject:Documentation_Group:Content_Ownership 01:07:36 it's important for me to know since my team does the base controller 01:07:53 @akim Have you seen the Helium release schedule? 01:08:22 yeah 01:09:10 all right, i guess you answered my question 01:09:20 AFAIK, that's the only timeline / schedule; but you might want to contact the base controller committers to see if they're working toward tighter timelines. 01:09:43 k 01:10:08 Yeah, the trick for us will be to get our tooling in place and then getting folks to do the authoring part. 01:10:08 may I add something before we close? 01:10:14 Please! 01:10:39 on the Content Ownership.. my initial feeling would be it could overwhealm the users 01:10:55 (number of guides, derivatives from base guides ,etc..) 01:10:55 So consolidate some of this stuff? 01:11:08 maybe.. I am just thinking 01:11:17 If I was a user where would I start 01:11:23 these components look good to us 01:11:28 +1 on per-project guides potentially being overwhelming. 01:11:34 but a normal user would be WTF is MD-SAL ;) 01:11:56 + all the other acronyms 01:12:08 just thinking out loud 01:12:18 OK, makes sense... I'll take another pass at the list and we can look it over in future meets... 01:12:22 anyways.. I'll let you close the call :) 01:12:32 sorry about that 01:12:41 No need to apologize... good point! 01:13:07 #action Table Design Docs/Templates for next time 01:13:21 OK, anything else? 01:13:33 Next time we'll chat on WebEx 01:13:40 thx :) 01:13:58 @paulz for the content list, do you want to add a "glossary" 01:13:58 #endmeeting