Attendees
| IRC nick
|
Real name
|
| apmon_ |
Kai Krueger
|
| pnorman |
Paul Norman
|
| ppawel |
Paweł Paprota
|
| RichardF |
Richard Fairhurst
|
| tmcw |
Tom MacWright
|
| TomH |
Tom Hughes
|
| zere |
Matt Amos
|
Summary
- Getting started / documentation
- The documentation on the wiki is too difficult to find and may be confusing for people unfamiliar with the project and its terminology.
- Difficulty (in part) comes from trying to bridge jargon gap and match people to the project and level they're interested in (e.g: "develop *using* OSM" vs. "contribute to OSM software")
- There was a general discussion about the advantages and disadvantages of curated (e.g: non-wiki) documentation, but it did not reach consensus.
- ACTION: ppawel make a wiki page with a (non-exhaustive) list of OSM projects, each with links to their issue trackers
- ACTION: zere find/generate links to tagged "getting started" issues on each of those (projects)
IRC Log
18:03:08 <zere> #startmeeting
18:03:08 <ewg-meetbot> Meeting started Mon Dec 3 18:03:08 2012 UTC. The chair is zere. Information about MeetBot at http://wiki.debian.org/MeetBot.
18:03:08 <ewg-meetbot> Useful Commands: #action #agreed #help #info #idea #link #topic.
18:03:23 <zere> minutes of the last meeting: http://www.osmfoundation.org/wiki/Working_Group_Minutes/EWG_2012-11-26
18:03:32 * TomH forks an extra thread
18:03:34 <zere> as ever, let me know if there's something that needs changing on there
18:04:31 <zere> last week we were discussing "getting started" / "junior jobs" and how to make it easier for newcomers to find those tasks and get involved.
18:04:51 <zere> there are 3 actions proposed:
18:04:57 <zere> 1. To make a wiki page with a (non-exhaustive) list of OSM projects, each with links to their issue trackers.
18:05:02 <zere> 2. To find or generate links to tagged "getting started" issues on each of those.
18:05:07 <zere> 3. To help curate existing issues into "getting started" categories.
18:05:30 * pnorman checks in, but briefly
18:05:31 <zere> do we want to discuss these actions and refine them? are they fine as they are and just need volunteers?
18:11:45 <tmcw> I think that's pretty straightforward/actionable.
18:12:04 <tmcw> though we'll have to ask the wiki homepage gatekeepers to link up a new page from the homepage or it will be censored
18:14:50 <ppawel> I think we should not create more new pages, just update existing 'developer portal'
18:15:02 <ppawel> http://wiki.openstreetmap.org/wiki/Develop
18:15:21 <tmcw> oh god that flowchart
18:15:28 <tmcw> okay we'll axe stuff on there and replace
18:15:42 <ppawel> it's not a flowchart :)
18:16:06 <tmcw> graph, or whatever
18:16:08 <tmcw> it's terrible
18:16:32 <ppawel> I think the contents are actually pretty good, but it needs polishing presentation-wise
18:16:50 <ppawel> and of course links from that page lead to countless outdated other pages....
18:16:59 <zere> yup. it definitely needs a refresh
18:17:20 <zere> and that flowchart / graphic is probably pretty useful... but not as the first thing a potential developer sees
18:17:26 <ppawel> I was thinking if this initiative should maybe be somehow connected with switch2osm
18:17:35 <ppawel> there is very similar content there
18:17:58 <zere> you mean a "developosm" site, or including it in switch2osm?
18:18:04 <tmcw> Is this linked from the home page at all?
18:18:31 <tmcw> ah 'create better tools' of course
18:18:34 <ppawel> zere, I mean that http://switch2osm.org/ has a lot of similar content
18:18:47 <zere> tmcw: yeah, we wondered about that last week... it's pretty terrible
18:18:57 <ppawel> seems like keeping two copies of the same content up to date is suicide mission
18:18:57 <tmcw> yes.
18:18:58 <tmcw> it is.
18:19:34 <apmon_> ppawel: How is it the same content as switch2osm? It seems both have rather different objectives?
18:19:46 <pnorman> switch2osm has been hugely helpful for my dev work - I use bits and pieces of the guides frequently as well as the packages. I don't use the complete thing, just parts. It saves me from having to compile osm2pgsql when I just want to use it and care about running an analysis on the data
18:19:57 <ppawel> http://switch2osm.org/serving-tiles/manually-building-a-tile-server/
18:20:06 <ppawel> http://wiki.openstreetmap.org/wiki/Deploying_your_own_Slippy_Map
18:20:34 <apmon_> That doesn't really talk about development of the tools though, just how to use them
18:20:57 <ppawel> and that's also part of current 'developer portal' in osm wiki
18:21:03 <zere> well, if it talks about building stuff from source, that's on the doorstep of development
18:21:37 <apmon_> Only because we still haven't managed to get the tools packaged and included in the big distributions
18:21:43 <pnorman> the wiki is about the slippy map (e.g. leaflet) and the switch2osm site talks about mapnik+osm2pgsql+etc
18:21:43 <tmcw> pnorman: you're not exactly switching2osm
18:21:50 <tmcw> you're kind of, you know, like a fairly elite hacker
18:22:07 <RichardF> curated docs is a big overall need for OSM... so far there's two particular projects (switch2osm and learnosm), but there's much more we could do
18:22:09 <tmcw> switch2osm's usefulness to you is a pretty good example of its failure to other people
18:22:17 <apmon_> If Ubuntu (and red hat) had up to date versions of the full toolchain, then switch2osm wouldn't really need a section on building from source
18:23:05 <pnorman> I'm not saying there's overlap between switch2osm and the wiki, just that that specific example isn't a great example of overlap
18:24:09 <apmon_> Which is perhaps a different topic to talk about. Should there be a concentrated effort to get more of the OSM tools into the distributions?
18:24:17 <zere> are we expanding the first action to essentially "lift" any useful documentation into a curated site (jekyll, or something) that we can host separately?
18:24:34 <pnorman> tmcw: the manually building part is a bit much for many but the PPA part isn't bad - although it could do with more content pointing to tools for designing your own stylesheet and deploying that style
18:24:34 <zere> apmon_: i got a sudden sense of deja-vu ;-0
18:25:20 <pnorman> the problem I have with wiki docs for the switch2osm content is that they failed badly to produce the docs that s2o provides
18:25:25 <ppawel> geez... http://wiki.openstreetmap.org/wiki/Developer_community
18:25:38 <ppawel> 50% of that page is about why a person should NOT help osm....
18:26:38 <apmon_> deja-vu? From where, or about what?
18:27:33 <pnorman> RichardF: is adding a table of contents for the headers on switch2osm a possibility while we're on the subject?
18:27:36 <zere> apmon_: getting up-to-date tools / software into distros / PPAs / developer VMs.
18:28:00 <RichardF> pnorman: how'd you mean?
18:28:29 <apmon_> True, I guess that was a big topic at the beginning of ewg... ;-)
18:28:38 <pnorman> RichardF: like on the larger wiki pages - a link to take me directly to "Software configuration" or whatever I want
18:29:01 * tmcw does not think that ppas are relevant to improving 'switch2osm' docs at all
18:29:37 <zere> ppawel: historically, there's been a lot of wasted time and effort when someone comes to OSM and says "no, no, no. you're doing it all wrong."... well, that's great and all, but as it says on the page - that's not actually helping.
18:29:40 <RichardF> pnorman: are you still @mac.com?
18:29:44 <pnorman> RichardF: yes
18:29:45 <ppawel> RichardF, do you think that somehow joining wiki refresh efforts with switch2osm content makes sense at this point?
18:30:21 <RichardF> ppawel: depends what you mean by "wiki refresh efforts" - switch2osm will never work if it's hosted on the OSM wiki, but as part of a wider curated docs effort, sure
18:30:37 <ppawel> zere, I understand that, I guess I've done my share of astronauting myself but it is a bit discouraging.. better solution would be to link to existing bugs/discussions
18:30:50 <pnorman> I think PPAs help significantly with switch2osm type content (s2o on the server side) because it allows you to get started without compiling everything yourself
18:31:01 <tmcw> gh
18:31:14 <tmcw> so, like 'switch2osm' if we think of it as 'switching from google maps'
18:31:24 <RichardF> pnorman: you have mail
18:31:26 <apmon_> tmcw: Not so much PPAs as actually getting it into main Ubuntu and debian repositories
18:31:40 <tmcw> we somehow presume that people will be willing to get a top-of-the-line server, learn the entire osm toolchain, and then the problem will be compiling from source vs using a ppa?
18:31:50 <tmcw> does this really sound okay to everyone?
18:31:58 <pnorman> argh. now my problem which was your problem is once again my problem
18:32:11 <zere> ppawel: i guess that's the "FIXME" bit. ;-)
18:32:14 <ppawel> RichardF, the idea is to somehow clean up the existing (technical) documentation on the wiki.. I think tha the technical content on switch2osm is very good - so maybe there's some way to reuse it, not sure...
18:33:28 <zere> tmcw: what alternative do you see?
18:34:02 <zere> the previous discussion was about moving to a "sudo apt-get install openstreetmap-tile-server" situation, which would result in a fully-working tile server.
18:34:12 <tmcw> document, say, using leaflet to include openstreetmap.org tiles
18:34:24 <tmcw> then document all of the options that you can use for alternative tile sources
18:34:33 <tmcw> and then, if neither of those two work, document how to diy it
18:34:38 <RichardF> tmcw: http://switch2osm.org/using-tiles/getting-started-with-leaflet/
18:35:00 <apmon_> tmcw: If you aren't using world wide maps, but only for e.g. a country, the hardware requirements aren't actually too bad
18:35:13 <zere> i don't think we really want to be promoting using OSM tiles. we're a data provider, not a tile provider.
18:35:17 <tmcw> apmon_: but the knowledge and time requirements are gigantic
18:35:44 <tmcw> zere: well then we aren't going to do a very good job of getting people to switch.
18:35:50 <apmon_> Well, that is where getting the packages into the repository is important
18:35:53 * RichardF is completely failing to see what the actual _point_ is of this discussion
18:35:53 <zere> tmcw: isn't that why you'd go talk to mapbox / geofabrik / gravitystorm / mapquest, etc...?
18:36:13 <apmon_> Then getting a test tile server up and running boils down to a few lines of apt-get
18:36:34 <tmcw> brb.
18:37:10 <apmon_> no need for "gigantic knowledge and time requirements"
18:37:21 <pnorman> Perhaps we could get to some action items? One being making another attempt at getting at least some of the packages into the repos?
18:38:28 <ppawel> hmm, we started out with discussing wiki pages and ended up with packaging :)
18:38:41 <zere> there's still gigantic time & hardware requirements - doing this worldwide is just very resource intensive.
18:38:53 <zere> ok. action 1
18:39:16 <zere> has this moved now from "wiki cleanup" to "make a curated site"?
18:39:45 <ppawel> what is the meaning of "curated" in this content? polished?
18:39:50 <ppawel> *context
18:40:02 <pnorman> not anyone can edit.
18:40:20 <ppawel> hmm...
18:40:22 <RichardF> yep. some sense of editorial ownership.
18:40:27 <zere> yes, that it has been put together as a cohesive whole and changes to it are edited to ensure high quality
18:41:06 <zere> there's no reason why this couldn't be done on the wiki, but it requires a lot more effort to ensure that the documentation stays at a certain level of quality
18:41:07 <ppawel> could this still be wiki-based though? something like exported versions of parts of the wiki would then form the site?
18:41:41 <zere> i think switch2osm is jekyll+github based. is that right, RichardF?
18:41:47 <zere> so it's sort-of a wiki.
18:42:02 <pnorman> it's pure wordpress I believe
18:42:24 <RichardF> it's pure wordpress
18:42:52 <zere> that's a pity. jekyll+github would allow more collaborative editing...
18:43:47 <zere> are we thinking curated vs. wiki now, then?
18:44:23 <RichardF> zere: sure, though speaking personally, the intersection of "people who understand git" and "people who can write good editorial content" is not perhaps as huge as you would like it to be :)
18:44:53 <zere> even using the inline web-based editor that github provides?
18:44:54 <pnorman> github has reasonable editors on its site for markdown that do the right thing with forking and everything
18:45:40 <zere> i guess it might be slightly different for a "develop4osm" site. git knowledge would be more widespread amongst developers
18:45:53 <RichardF> ugh, Markdown :( - but seriously, if someone wants to port switch2osm to something else, be my guest
18:45:58 <ppawel> what is the problem with using wiki for this - simply updating current documentation using switch2osm content or something? I feel like forking technical documentation off wiki to external site is not so good...
18:46:15 <RichardF> ppawel: the wiki is a complete disaster for docs, is pretty much the problem.
18:46:26 <ppawel> oh, didn't know that...
18:46:30 <RichardF> every time you write something, it accumulates nonsense for two reasons:
18:46:34 <zere> RichardF: we're not talking about porting switch2osm - we're talking about whether we want the developer site somewhere else. switch2osm is just an analogy / example.
18:46:47 <pnorman> ppawel: because the wiki has failed badly in the past for docs, is still failing and will likely continue to fail
18:46:48 <RichardF> 1. "this didn't work for my 0.1% environment so I'll change the docs to reflect that"
18:47:04 <RichardF> 2. "I HAVE AN IMPORTANT HOBBYHORSE AND YOU MUST KNOW ABOUT THAT"
18:47:33 <ppawel> really? most pages with useful content I've seen have a handful edits per year...
18:47:54 <pnorman> before I change a well-written doc (as opposed to some of the wiki docs where they're clearly wrong already) I spin up a VM and test the *entire* procedure start to end
18:48:01 <ppawel> I agree wiki may be failing for tag documentation
18:48:14 <RichardF> and for editor documentation, beginners' guide documentation, setting-up-the-Rails-port documentation...
18:48:23 <zere> s/may be/is always/
18:49:11 <ppawel> so why not just use some mediawiki extension for page locks?
18:49:41 <pnorman> anyways, off to survey a new bridge (yay!), pay for new glasses (ouch) and see if the new road that opened is highway=trunk or highway=motorway. RichardF, I might poke you later about switch2osm stuff.
18:49:46 <RichardF> pnorman: yay :)
18:50:27 <RichardF> ppawel: sure, if someone is volunteering to run that, that could work. I'm not aware that anyone has done so yet
18:50:38 <zere> my feeling is that it would be easier to keep the docs up to date with the software if you're using the same toolchain for each: a text editor and git.
18:50:47 <zere> s/each/both/
18:51:01 <pnorman> my vote is for some kind of git repo + html generator. git may exclude some people who can write good content from contributing directly but it's no worse than it is with wordpress where you can't contribute directly at all
18:51:29 <pnorman> worst case they fire off an email with the changes to someone who can manage git but can't write, no worse than now
18:51:34 <zere> the comparison is wiki vs (something else), not wordpress vs (something else), though...
18:51:41 <ppawel> soon we will be writing software for editing documentation about software...
18:51:55 <zere> did you just say "pandoc"? ;-)
18:52:14 <apmon_> Is there a good place where all of the options of osm2pgsql and mod_tile are described?
18:52:54 <ppawel> RichardF, what do you mean by "run that"? is it a problem to install such extension at wiki.osm.org?
18:53:26 <zere> ppawel: he means "look after", "take responsibility for". installing mediawiki extensions shouldn't be a problem
18:53:36 <RichardF> indeed
18:54:11 <ppawel> is it more effort than setting up an external site and new editing toolchain...?
18:54:37 <RichardF> for me, yes, it is, which is why I did switch2osm the way I did
18:54:45 <RichardF> ymmv
18:55:36 <zere> as someone who has cleaned up wiki documentation before, my problem was that i did it once and then looked at it again 6 months later and it had severely bit-rotted. the real problem is that i didn't put in the time to regularly check the page, ensure the docs were up to date, ensure the edits people had made were incorporated in a way that was helpful to most visitors, etc...
18:56:29 <zere> now, i'm not saying that moving away from a wiki will make everything effortless, or that we'll be able to write docs once and never look at them again.
18:57:08 <zere> my feeling is that it works better if the effort put in is on a "pull" model, rather than the "poll / callback" model required on the wiki.
18:58:01 <zere> however, i live in hope. ppawel, would you be willing to give action 1 a try?
18:59:01 <ppawel> can you restate what it was? :) I cannot find it in scrollback
18:59:11 <zere> first action: make a wiki page with a (non-exhaustive) list of OSM projects, each with links to their issue trackers
18:59:21 <ppawel> ah ok this one
18:59:41 <zere> although i think it spread slightly to also include cleanup of the general dev documentation. i'll call that action 1b ;-)
19:00:26 <ppawel> yes I can take a stab at it. there is such a list on the main page - http://wiki.openstreetmap.org/wiki/Develop but it looks like it needs love
19:01:55 <zere> thanks :-)
19:02:10 <zere> #action ppawel make a wiki page with a (non-exhaustive) list of OSM projects, each with links to their issue trackers
19:02:22 <zere> did you want 1b as well?
19:02:56 <ppawel> I think it may be a bit general in scope
19:03:05 <zere> fair enough - one step at a time
19:03:08 <ppawel> maybe it will be an ongoing effort
19:03:14 <zere> any volunteers for "find/generate links to tagged "getting started" issues on each of those"?
19:03:17 <ppawel> or maybe we can make more fine grained tasks
19:03:48 <zere> RichardF, apmon_, pnorman: fancy volunteering for the above?
19:04:51 <zere> i guess that's a "no".
19:05:12 <zere> #action zere find/generate links to tagged "getting started" issues on each of those (projects)
19:05:21 <zere> final action: help curate existing issues into "getting started" categories
19:05:27 <zere> that seems a bit "ongoing" as well
19:06:10 <ppawel> yes I think so too
19:06:33 <zere> ok, well, we can leave that one until the first two are done. then maybe split it up by project
19:06:59 <zere> i figure we could all probably take a look at the wiki in the next week and see if there's something clearly wrong / out of date to fix
19:07:35 <zere> also, perhaps we need to think about a better organisation (or any organisation at all) of the dev-related wiki pages.
19:07:46 <zere> but we can discuss that next week...
19:07:58 <ppawel> yeah I also wonder about language translations
19:08:07 <ppawel> if we were to reorganize stuff...
19:08:20 <ppawel> they will get badly out of sync.. not sure what is the standard operating procedure for this
19:08:22 <zere> you mean losing the existing ones?
19:08:34 <zere> yeah. i'm not sure there is a procedure.
19:08:51 <ppawel> yeah, like for example this main page "Develop" is translated into a number of languages
19:09:12 <zere> but if we do change a lot of stuff, perhaps then we'd reach out to other language communities to help with the translation
19:09:32 <ppawel> ok
19:09:43 <zere> although (very anglocentric of me) i find most developers usually speak very good english
19:09:59 <ppawel> that's true
19:10:28 <ppawel> (I also think there should only be one language on earth but that's probably out of scope here :)
19:10:42 <zere> volapuk? :-P
19:11:01 <zere> ok, digressing rapidly
19:11:14 <zere> thanks, everyone! hope to see you next week :-)
19:11:16 <zere> #endmeeting