Working Group Minutes/EWG 2013-10-21

Attendees

IRC nick Real name
apmon Kai Krueger
gravitystorm Andy Allan
pnorman Paul Norman
TomH Tom Hughes
zere Matt Amos

Summary

  • 2014 planning:
    • Summarised previous goals:
      • Continue to provide hack event funding, but publicise it better.
      • Help produce better developer docs for OWL and osm2pgsql / mod_tile.
  • Focus / remit of EWG:
    • gravitystorm suggested that a wider focus besides the documentation work would produce a livelier and larger group of regular attendees.
    • Such discussions have happened in EWG meetings, but are perhaps technically out of remit.
    • How to signal that such discussions are welcome - just changing some text on the remit part of the EWG page isn't really going to be noticed?
  • osm2pgsql / mod_tile developer documentation:
    • Low hanging fruit: Have standard README, LICENSE files, conventional directory layout, documentation for unexpected things (C/C++ mix, for example).
    • Moving separate components into separate directories can also help.

IRC Log

17:04:45 <zere> minutes of the last meeting: http://www.osmfoundation.org/wiki/Working_Group_Minutes/EWG_2013-10-14
17:04:53 <zere> please let me know if anything needs fixing
17:05:16 <zere> #topic previous actions
17:05:32 <zere> i'm still trying to put together a draft blog post. if anyone would like to help, please let me know.
17:05:49 <zere> gravitystorm: anything on the previous events or OWL docs front?
17:06:01 <gravitystorm> zere: nope
17:06:07 <gravitystorm> no change on either
17:07:20 <pnorman> morning
17:08:27 <zere> gravitystorm: anything you need, or are they just going slowly?
17:09:15 <gravitystorm> zere: just a lack of time (busy with work stuff). Of course, there's nothing stopping other volunteers from doing them - the previous events survey especially
17:10:03 <zere> cool. if anyone would like to help out, i'm sure they can get in touch with you here or via email, of course. (hint, hint) ;-)
17:11:16 <zere> #topic 2014 planning
17:11:56 <zere> so far, i think we've agreed we want to continue to provide funding for hack events - but communicate that better.
17:12:09 <pnorman> wasn't that on our 2013 list too?
17:12:14 <zere> yup
17:12:33 <zere> i think we also wanted to generally improve documentation, with a specific focus on OWL and osm2pgsql.
17:13:10 <zere> was there anything else that we want to put out there as a goal for 2014 - something we can drive towards?
17:13:50 <gravitystorm> having more than 50% of the lurkers joining in with the meetings? :-)
17:15:21 <zere> the goals have to be achievable, right? ;-)
17:18:06 <gravitystorm> well, on a less flippant note, do we see the need to engage more people with EWG itself? I mean, our list of "what's been done" each week isn't particularly lengthy, and the other alternative - more work from a small number of people - isn't going to happen.
17:18:33 <zere> it seems that way more people get involved when it's technical, much more than for documentation or planning stuff. which is understandable.
17:19:12 <zere> so perhaps the "discussing technical stuff" aspect is better separated from the "boring bits"^W^W documentation and planning stuff?
17:20:11 <zere> if no one is interested in having the discussion here, we could always take it to legal-talk@, or tagging@ - those guys are always up for a (lengthy) discussion ;-)
17:21:20 <gravitystorm> X-)
17:22:17 <gravitystorm> well, I guess it depends on what we want EWG to be. I mean, many of the lively conversations a few months ago were, in my eyes, straying into general development. So there's an argument that if only to ensure healthy discussions, we could widen our remit
17:22:35 <gravitystorm> while cunningly occaisionally discussing boring things with the engaged audience
17:22:52 <gravitystorm> so, front page redesign. How many pixels high should the nav bar be?
17:23:26 <TomH> 7, or 14 on Wednesdays
17:23:39 <pnorman> 8-1 or 12+2
17:24:44 <gravitystorm> we should only be using prime numbers, imho, so 7 works for me
17:26:00 <zere> wait, wait
17:26:23 <pnorman> what base should we be representing these numbers in?
17:26:30 <zere> we can't possibly discuss the size of the nav bar before we discuss its colour
17:26:46 <gravitystorm> pnorman: I don't mind, so long as it's a prime base
17:27:22 <pnorman> what about a non-integer base?
17:27:28 <gravitystorm> zere: I'd be interested in your thoughts on the remit vs focus vs engagement
17:27:28 <zere> i'm assuming "nav bar" is some new cool word - just like "genius bar" for "support desk", this is for "bike shed"? ;-)
17:29:02 <TomH> as against "chav bar" which is something else entirely
17:31:24 <zere> gravitystorm: i'm not sure what you mean...
17:33:01 <gravitystorm> so my hypothesis is that if we stick to core EWG stuff - e.g. documentation - then attendance at the meeting falls, since that's seen as Boring Shit. Alternatively, if we slaken off the constraints on the remit, so that it's not only getting-devs-started discussions, then we can draw more of a crowd and, perhaps, get more core stuff done via a halo effect
17:34:42 <zere> sounds like a good plan. i'm not sure that other types of discussions have ever been out of remit, though?
17:35:25 <zere> you think it would help to add "general technical discussion" to the list of explicit "includes" rather than having it as a "typical activity"?
17:36:24 <zere> and what, in practice, would we do to make that change. i'm not sure that changing the remit - in and of itself - has much effect... we'd want to run the meetings differently?
17:37:01 <apmon> If we explicitly include development (rather than just "meta-development"), then we should communicate that more widely to let everyone know
17:39:43 <apmon> regarding documention discussion from earlier on. Was there anything specific regardings osm2pgsql that is missing?
17:40:08 <gravitystorm> out-of-remit discussions - mod_tile backends, osm-carto performance, moderator permissions on delete notes, etc
17:40:25 <pnorman> you mean what we've been doing for some time?
17:40:53 <gravitystorm> e.g. there's nothing on the summary of http://www.osmfoundation.org/wiki/Working_Group_Minutes/EWG_2013-04-01 that is about encouraging more developers to get started developing
17:41:17 <zere> gravitystorm: i don't think any of those discussions were out of remit, though...
17:41:46 <apmon> Is there any reason to have those in EWG though rather than on osm-dev or the mailinglists?
17:42:26 <gravitystorm> zere: of course, you started all this so you understand the remit more than most. But which bit of http://www.osmfoundation.org/wiki/Engineering_Working_Group would they come under?
17:42:47 <gravitystorm> "guiding the development process" perhaps?
17:42:50 <zere> only that EWG, being a "real time" forum which is to some extent moderated, it's often easier to get a consensus. mailing list discussions can go on ad infinitum.
17:43:23 <zere> gravitystorm: "typical activities" includes:
17:43:24 <apmon> I mostly agree with gravitystorm, that those topics are at best in the "grey area" from what I thought the core mission of EWG should be
17:43:31 <zere> EWG typically acts as a technical forum, and meetings generally cover areas including:
17:43:34 <zere> Review of patches / PRs and discussion of how to improve them.
17:43:37 <zere> Improvements to documentation and other technical information.
17:43:39 <zere> Knowledge sharing and technical problem-solving.
17:44:44 <zere> the third is probably both the most management-speak and the most vague. and yet, the most inclusive ;-)
17:45:33 <zere> of course none of this is ever set in stone - if you think that adding something, or changing the wording, would help then i'd love to hear about it.
17:45:50 <zere> but i'm not sure anyone attends EWG because of what they read on the OSMF wiki ;-)
17:48:28 <gravitystorm> well, you never no. Perhaps somewhere there's even a developer who gets started by reading INSTALL.md
17:48:35 <gravitystorm> s/no/know/
17:50:31 <apmon> In case there is some time (as I missed the previous meetings), would it be possible to circle back to the osm2pgsql / mod_tile documentation issue?
17:52:45 <zere> i think this is worth discussing more. i must confess i don't really have any coherent thougths on the topic... perhaps next week we could have a fuller discussion of what it would mean to widen our remit.
17:52:58 <zere> #topic osm2pgsql / mod_tile documentation
17:53:46 <apmon> Given that osm2pgsql and mod_tile seem to be at the top of "needs more documentation" and I am supposed to be resonsible for them, I am wondering what would be most helpful
17:53:54 <zere> we gathered some information on opinions of the quality of documentation and need for developers across various bits of OSM-related software.
17:54:19 <apmon> particularly gravitystorm, given your consulting work, you might know best what people are struggeling with and what they are looking for
17:54:23 <zere> i should say "developer documentation", because it was more about how to get involved with it, rather than just how to run it.
17:54:58 <apmon> OK, well that pretty much doesn't exist at all
17:55:11 <gravitystorm> apmon: yeah, the focus of this thing is documentation for new developers, so my clients aren't the target here.
17:55:19 <gravitystorm> apmon: :-)
17:55:23 <zere> apmon: this was the original questionnaire: https://docs.google.com/forms/d/1H6Ud7_dYklGNGNKrbywX5t1matPTPShbqwCq9T0U1Z4/viewform
17:55:56 <pnorman> I know for getting involved in the development of some stuff the first question I have is how to run it
17:56:27 <zere> i think in the "dev docs quality" and "need for developers", OWL came top, then osm2pgsql, after that the result was different.
17:56:32 <apmon> Yes, most of the time, running and compiling it is the biggest issue. After that I just dig myself through the code
17:56:36 <pnorman> by run I mean build/compile/whatever. in the case of P2, it convinced me to not contribute
17:57:58 <zere> i think if we think about how people come to modify software; a large number either want to fix a bug or they want to add a feature. i suspect the majority fall into one or other of those categories.
17:58:09 <apmon> same here. Didn't feel like I knew how to get the toolchain for P2 up and running
17:58:18 <apmon> Is that an issue with osm2pgsql though?
17:59:23 <zere> so the issue is not only building, installing and running the software - it's also the next bit; how to get a good overview of what the software is doing, which source files are involved in which bits, etc...
17:59:34 <apmon> Perhaps one can provide "source packages" for those, to make sure they install all of the developer libraries and tools?
18:00:16 <pnorman> osm2pgsql uses a much more conventional toolchain and is fairly easy to build. but if someone doesn't know what all the command line options do they're going to have a hard time doing much development
18:00:50 <zere> on the other end of the scale, JOSM and rails_port alledgedly had the least worst dev docs. for rails_port it's probably because it's a largely standard rails app, so there's a convention to how it's layed out, how bits are named, etc... which helps.
18:01:31 <zere> things like OWL, osm2pgsql and cgimap don't have those conventions.
18:02:05 <zere> i really want to get some docs started for cgimap; an overview, architecture, how to run the tests, how to write tests, etc..
18:02:11 <apmon> Can one assume people roughly know "what it does" and just not "how it does"?
18:02:34 <gravitystorm> so my suggestions would be - creating a CONTRIBUTING.md discussing pull requests, have a LICENSE file, move the files into places where devs would expect them (src and include, perhaps) which has the side effect of it being less scrolling to get to the README, rewriting the readme into markdown or doing whatever needs doing so that the ==== disappear
18:02:52 <gravitystorm> I mean, it's all trivial stuff, but the idea is to remove the sand in the gears for new developers
18:02:57 <zere> i think by the time someone is interested in modifying the software, one can assume they've run it before. or at least seen it running and roughly understand what it's supposed to be for.
18:03:29 <apmon> good. Yes, I would hope that one can assume that.
18:04:01 <gravitystorm> explaining whether stuff should be in C or C++ is another one, having the mixture is a bit unexpected
18:05:05 <zere> i think the thing is perhaps someone comes along and wants to write another backend for osm2pgsql for spatial mongodb or something. or they think they can improve the robustness of the polygon reconstruction or something. i guess it's daunting coming to the software cold, and not knowing where to look for stuff.
18:05:45 <apmon> So perhaps subdividing it further into directories would help somewhat
18:06:00 <zere> i know there's grep and ack-grep and asking on #osm-dev, but as gravitystorm says, it would remove a lot of friction if people could understand the basics of how the software fits together from written docs first.
18:06:08 <apmon> i.e. group the front-end / slim-mode / and backend code into separate directories?
18:06:26 <zere> that might help, yeah.
18:06:46 <zere> personally, i think the most important directory is the one called "docs/" with the .md files in it ;-)
18:07:18 <apmon> I'll try and merge the multi-threading branch into osm2pgsql and then have a go at moving more things into subdirs
18:07:45 <zere> that would be awesome :-)
18:07:49 <gravitystorm> I think the thing is to have as few surprises as possible. So if there's conventions for c/c++ directory layouts, then best to follow them. I'm no expert on that though.
18:08:17 <zere> and if anyone feels like helping out... it would be awesome for cgimap & OWL, and probably a lot more too!
18:08:49 <zere> gravitystorm: the wonderful thing about c/c++ conventions is that there's so many to choose from.
18:14:52 <zere> ok, sounds like that's it for tonight. thank you, everyone, for coming!
18:14:58 <zere> i hope to see you next week