Attendees
| IRC nick
|
Real name
|
| apmon_ |
Kai Krueger
|
| ppawel |
Paweł Paprota
|
| RichardF |
Richard Fairhurst
|
| tmcw |
Tom MacWright
|
| zere |
Matt Amos
|
Summary
- Getting started / documentation
- There was more discussion about what the "top level" for developers should look like on the wiki in order to best direct them where they're interested in going.
- ACTION: tmcw to clean up the wiki/Develop page as suggested (see logs below).
IRC Log
18:07:04 <zere> #startmeeting
18:07:04 <ewg-meetbot> Meeting started Mon Dec 10 18:07:04 2012 UTC. The chair is zere. Information about MeetBot at http://wiki.debian.org/MeetBot.
18:07:04 <ewg-meetbot> Useful Commands: #action #agreed #help #info #idea #link #topic.
18:08:11 <zere> apologies, i haven't managed to get the minutes online yet. the meetbot logs are up at http://matt.dev.openstreetmap.org/osm-ewg/2012/osm-ewg.2012-12-03-18.03.html, however.
18:08:25 <zere> actions from the last meeting:
18:08:46 <zere> ppawel to make a wiki page with a (non-exhaustive) list of OSM projects, each with links to their issue trackers.
18:09:01 <zere> and my own: zere find/generate links to tagged "getting started" issues on each of those (projects)
18:09:23 <zere> i have more apologies, as i haven't done my action either - i'll keep it on for the next meeting.
18:12:33 <ppawel> hello
18:13:14 <ppawel> I have not done a lot myself, mostly I just cleaned up https://trac.openstreetmap.org/
18:13:24 <ppawel> added 'create' and 'view' links to main projects
18:14:16 <ppawel> as for the more comprehensive list... I think we would need to start from the beginning with this - I mean decide how to present the information on the wiki (Develop page), right now it is a mix of everything and nothing...
18:15:08 <ppawel> I think as the foundation should be separation between using OSM for development and actually developing OSM
18:15:55 <ppawel> right now there's just a large list of different topics, projects, links
18:16:21 <zere> "build using OSM" vs "contribute to OSM code" - yeah, that's a pretty big distinction
18:18:06 <ppawel> also some stuff overlaps... like Nominatim - on one hand it is the main search server at osm.org but on the other you can also use it as a standalone solution
18:18:18 <zere> so do you think it's worth taking away all the different entry points on the wiki and having just a single "Developer Information" page, which filters through a set of these sort of "what do you want to do?" questions?
18:19:48 <ppawel> I think this can be iterative... there is just too much information to process it, eg. change entry points as you say... I think we could start with the main page of the developer "portal" and introduce this distinction
18:20:36 <ppawel> I also added this... http://wiki.openstreetmap.org/wiki/Talk:Main_Page#Link_for_developers_should_be_more_exposed
18:24:11 <zere> ok. so what's the first iteration? change http://wiki.openstreetmap.org/wiki/Develop to have one section for developing *using* OSM and one for developing OSM *code*?
18:24:18 <zere> where does the line get drawn?
18:25:20 <zere> i mean; setting up your own slippy map is clearly "using", and TTTs are clearly "code", but what about stuff like the API documentation?
18:25:36 <zere> you need that to code, but also for some uses.
18:26:22 <ppawel> yeah.. the line is blurry for certain components
18:27:18 <ppawel> but maybe things can be on both sides of the line... just documented from different points of view
18:27:38 <ppawel> API as in http://wiki.openstreetmap.org/wiki/API_v0.6 vs API as in Rails Port docs
18:29:11 <ppawel> I think it could be good to maybe name it somehow...
18:29:39 <ppawel> I mean... like in KDE - they have their "platform" and people can either work on it (kdelibs etc) or they can build applications on it using APIs
18:30:17 <ppawel> http://kde.org/developerplatform/
18:30:29 <ppawel> not sure if something like this exists in OSM world... stable enough to be captured
18:30:49 <ppawel> the platform is whatever you want and the only "stable" thing is the data I guess...
18:31:19 <ppawel> so the platform would mean only "osm.org platform" really, but maybe that's enough.. after all there has to be some centralization at some point...
18:31:54 <zere> i guess rather than providing software APIs, we have a pretty stable HTTP API for editing, and a very stable XML format for "planet" type data.
18:32:53 <zere> but as for software - there are many libraries for parsing and using OSM data. although i think it's probably fair to say that most people use the tools (osm2pgsql, osmosis, etc...) rather than the libraries directly
18:34:20 <ppawel> yeah that's true
18:34:50 <ppawel> so maybe a different approach then... we start with the chicken (or egg :-) and tell people what they can do with it
18:35:02 <ppawel> by chicken/egg I mean OSM data
18:35:54 <ppawel> not sure what's the different though, it's getting kind of abstract... I've seen there are job titles "information architect", I guess they are meant to do such stuff...
18:36:07 <zere> pffft.
18:36:46 <ppawel> but I'm sure they are overpaid and we can do it ourselves :-)
18:37:56 <ppawel> I guess another (complementary) approach is 'picture is worth a thousand words' - so redoing this very complicated-looking diagram
18:38:14 <ppawel> and maybe even make it clickable to act as a table of contents to some degree?
18:38:59 <zere> first principles: we're talking about people coming to this page because they've seen "develop" or similar keyword, and that overlaps to some degree with what they want to do
18:39:30 <zere> assuming little or no knowledge of OSM... is even a simplified diagram going to help?
18:40:27 <zere> this starts to deviate from "providing information" towards "education", and i don't have any idea what's best to do in that situation
18:40:41 <ppawel> depends on what do we assume about such visitor... I'd say they need to be able to read a simple diagram in order to write some code :)
18:41:07 <ppawel> exactly... I think we should not teach people to code or understand technical stuff and assume they do at some basic level at least
18:41:36 <ppawel> but right now looking at this diagram is painful no matter who you are...
18:42:37 <zere> how simple can we make it? a server in the middle and then a cloud of users/editors to one side, and a cloud of consumers on the other?
18:43:30 <ppawel> I guess it would be hard to make it simpler than that...
18:43:44 <zere> but is it too simple?
18:44:08 <ppawel> I'm just looking through existing content to see if major points are covered...
18:44:41 <ppawel> on one side we would then have editors, on the other - rendering, data manipulators..
18:44:58 <ppawel> somewhere in the middle (in the cloud) all topics related to rails port
18:45:06 <tmcw> why not two paragraphs explaining what connects to what, and a list of _good_ one-sentence descriptions/languages/links to github of all 'important' subprojects
18:46:38 <zere> it's hard for me to think differently, but it does seem to me that the major split is between stuff that communicates with the API bi-directionally, and stuff which consumes (oneway=yes) data from the project. of course, there are gery areas, but that seems to cover it.
18:48:07 <ppawel> yeah that's a good point about bi-directionality
18:48:40 <ppawel> I was thinking about editors being on both sides (as consumers and API users) but what you said makes this simpler
18:49:10 <zere> tmcw: do you mean something like "The core of OSM is the editing *API*. People contributing to the map use an *editor* to interact with the *API* through a set of *API calls* for reading and writing subsets of the data. Data from the OSM API is released for consumption by various systems; for example *tile rendering*, *geocoding*, etc..."
18:49:24 <zere> where the *emphasised* things would be links to more information
18:49:28 <tmcw> we're talking about an intro for developers, right?
18:49:55 <tmcw> not an intro for users. aka a replacement for /Develop on the wiki?
18:50:25 <zere> yes. but not sure whether the developer is interested in developing using OSM as a service / data source in their own application, or actually contributing to one of the OSM tools.
18:50:59 <tmcw> right now the /Develop page is for the latter, and it should stay that way
18:51:28 <tmcw> other sites will do a better job of 'softer' user cases
18:51:28 <ppawel> it contains all kinds of content
18:51:48 <zere> ok, but then we need some other page to be able to filter the former to a page which will help them
18:52:03 <tmcw> no, you just need a link at the top
18:52:11 <zere> otherwise they'll be very confused by talk of setting up rails ports and so forth
18:52:15 <tmcw> it's not like tons of people are landing on /Develop - it takes me a few minutes to find the link every time
18:52:22 <tmcw> so, a link at the top.
18:52:31 <tmcw> like "Just want to use OpenStreetMap? See X"
18:52:36 <tmcw> doesn't seem like a very tricky problem
18:53:00 <ppawel> what about existing content for users? why not leverage/update that and include it in the Develop page?
18:53:13 <tmcw> 'existing content for users'?
18:53:14 <zere> "just want to use" => "just want to be a user of / editor" vs. "just want to use OSM APIs"... documentation is hard. :-(
18:53:47 <tmcw> semantic battles aside
18:53:55 <RichardF> zere: and "API" => "Google Maps-like API pls" vs "OSM REST API"
18:53:57 <apmon_> The entry portal to /Develop should imho just be a short page splitting people off into the different categories and then linking to sub pages for each.
18:54:03 <tmcw> ugh
18:54:07 <apmon_> Explaining who is likely to want what
18:54:09 * tmcw this is why the wiki sucks
18:54:23 <zere> s/the/every/
18:54:53 <tmcw> these problems are seriously not that tricky, this is just overthinking them.
18:54:56 <ppawel> apmon_, this sounds good.. trying to fit everything on one page may be unrealistic, even in the ToC form
18:56:11 <zere> tmcw: ok, back to concrete suggestions: you're saying that we should just replace the page with a couple of explanatory paragraphs at the top, then a list of projects - each with a succinct description
18:56:52 <zere> it sounds like a good idea to me
18:57:01 <zere> anyone volunteering to have a crack at it?
18:57:05 <tmcw> I can do this
18:57:22 <zere> indeed, i see you've already done some work on it - thanks :-)
18:58:10 <zere> #action tmcw to clean up the wiki/Develop page as suggested
18:58:43 <zere> i notice we're at the top of the hour. are there any other items that people would like to discuss?
18:58:45 <ppawel> so what we discussed for 30 minutes ended up as adding one sentence descriptions to random links that exist on this page?
18:59:33 <ppawel> not sure how this improves the situation...
18:59:46 <apmon_> tmcw: Imho the list of projects should be clearly split into the two categories: "App developers" "OSM infrastructure developers"
18:59:54 <zere> ppawel: i think this is basically different. tmcw is talking about organising this page for the benefit of people who've come to contributor to OSM tools.
18:59:57 <tmcw> can I just jfdi for about an hour?
19:00:08 <zere> tmcw: please do
19:00:09 <tmcw> it seems like you guys are angry that there's not a more complex solution
19:00:15 <tmcw> k, brb.
19:00:36 <zere> no, we were discussing something quite different. hence the confusion
19:00:55 <ppawel> angry? you seem to take every comment personally... I'm just not sure what you referred to with the idea of writing two paragraphs and we're done
19:01:08 <ppawel> as zere explained it is a different topic then it's clear now
19:01:41 <zere> what we were discussing, and what apmon_ is talking about, is a page where people can go if they're not sure what they want.
19:02:22 <apmon_> As OSM is kind of different to many other projects (uncoordinated and diverse), there is often quite a confusion of how the different parts all fit together. So having a list of "projects" or "terminology" and explaining each briefly does sound fairly helpful as an introduction
19:03:41 <ppawel> well sure, I just didn't realize that tmcw was not talking about the topic we were talking about...
19:04:03 <apmon_> was he not? Seems like it fits
19:04:49 <ppawel> what zere said above... one thing is a general home page for technical people, another thing is 'developer intro' as tmcw called it
19:05:35 <ppawel> or are they the same? not sure.. I just got confused when he jumped in that's all..
19:06:29 <apmon_> One should be a portal into the other. I.e. the index page of the documentation
19:06:42 <ppawel> I would be interested in trying to put together a "landing page" which redirects people to specific areas
19:07:18 <ppawel> I assumed we would just refine the Develop page but it can just as well be a separate page
19:08:38 <ppawel> I think there should be actions to improve current situation which is not good... Contribute link -> Create better tools and then you have a mixture of different stuff (using OSM vs developing OSM)
19:08:44 <zere> we have all kinds of problems mixed up in here. there's people trying to find out all sorts of information - specific information hopefully can be found on the tool's own site, but also domain information about how stacks (e.g: tile rendering) fit together which may or may not be on the tools' sites, and general information about how the whole project fits together
19:09:36 <zere> right - and we're making good progress. as tmcw said, much of it we can jfdi, then come back around to see how it fits together and what needs tweaking
19:10:28 <ppawel> right, I could have jfdi myself, just thought it is worth discussing...
19:11:20 <ppawel> but I have a lot of OWL work so I can tune out of the wiki work and come back in a few days
19:15:55 <zere> yes, it is worth discussing, and i'm sure we'll discuss what the new page looks like, and whether there are improvements we can make to it.
19:17:01 <zere> as we get closer to something that's fit for purpose, i'm sure the discussions will be more important. perhaps we'll even think it's worth locking the wiki page to ensure that it doesn't bit-rot away again...
19:20:49 <tmcw> locking the wiki page?
19:23:01 <zere> yeah, perhaps. if it's necessary. the alternative is to keep an eye on it and making sure that changes don't lower the usefulness of the page.
19:23:11 <zere> but we haven't been very good at that, historically.
19:23:56 * apmon_ wonders what the tools own page for mod_tile and osm2pgsql is?
19:24:22 <zere> e.g: there's a danger that people would see the "list of _good_ one-sentence descriptions/languages/links to github of all 'important' subprojects" degenerates into a wikipedia-style list of random bits of software.
19:24:34 <apmon_> I wanted to document a new configuration option in mod_tile, and didn't know where to best add the information
19:24:52 <zere> apmon_: where would you like to do it?
19:25:04 <apmon_> I don't know :-S
19:25:09 <zere> README.md in the mod_tile source?
19:25:31 <zere> page on the github wiki? page on the OSM wiki?
19:25:51 <zere> i mean, at the end of the day it doesn't matter where it is exactly, as long as it's well-written and up-to-date.
19:25:56 <apmon_> I added it to the example .conf file. But that is in the debian folder, so presumably no-one will find it there
19:26:36 <apmon_> It would help if there was a certain consistency between tools
19:26:49 <apmon_> So that one can build up an expectancy of where to find what information
19:27:24 <zere> sure. but the first step is surely to create the information in documents.
19:27:41 <zere> after that, we can talk about homogeneity and POLS
19:28:29 <apmon_> POLS?
19:29:25 <zere> Principle Of Least Surprise - usually in the context of an API / language, but works for documentation too
19:29:36 <apmon_> ah, OK
19:30:13 <zere> apparently it's "the principle of least *astonishment*" - http://en.wikipedia.org/wiki/Principle_of_least_astonishment
19:30:32 <zere> i was astonished to find that out, as i was sure it was "surprise".
19:32:06 <apmon_> I also thought it was surprise. So I guess the principle violates it self... ;-)
19:32:33 <zere> :-)
19:33:09 <zere> i guess now is as good a time to close the meeting as any. thanks to everyone for coming, and hope to see you next week!
19:33:12 <zere> #endmeeting