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