Attendees
| IRC nick
|
Real name
|
| apmon_ |
Kai Krueger
|
| ppawel |
Paweł Paprota
|
| tmcw |
Tom MacWright
|
| zere |
Matt Amos
|
Summary
- Getting started / documentation
- The Wiki/Develop page has been re-worked.
- Still concern over useful documentation reaching the right audience - a large number of people are not (initially) looking for highly technical information, but that technical information does need to be easy to find and understand.
- There was single approach to this which received consensus agreement.
IRC Log
18:13:58 <zere> #startmeeting
18:13:58 <ewg-meetbot> Meeting started Mon Dec 17 18:13:58 2012 UTC. The chair is zere. Information about MeetBot at http://wiki.debian.org/MeetBot.
18:13:58 <ewg-meetbot> Useful Commands: #action #agreed #help #info #idea #link #topic.
18:14:28 <zere> minutes of the last couple of meetings: http://www.osmfoundation.org/wiki/Working_Group_Minutes/EWG_2012-12-03 and http://www.osmfoundation.org/wiki/Working_Group_Minutes/EWG_2012-12-10
18:15:05 <zere> actions from the past couple of meetings are all about http://wiki.openstreetmap.org/wiki/Developers and friends
18:16:34 <zere> does anyone (ppawel, tmcw?) want to say something about the changes there and anything that's left outstanding?
18:16:52 <tmcw> eh
18:17:43 <tmcw> synopsis is that I rewrote the page, ppawel re-rewrote it, I disapprove of the re-rewrite but also am moving more towards not using the wiki for introductory material of this type.
18:17:47 <ppawel> there was some discussion and confusion about this page - see http://wiki.openstreetmap.org/wiki/Talk:Develop#Rename_according_to_purpose.3F_.2B_Developers_page ... but at the moment the situation is that the layout is updated
18:18:15 <tmcw> the last pre-rewrite revision is http://wiki.openstreetmap.org/w/index.php?title=Develop&oldid=841294
18:18:42 <ppawel> yes, after talking with Harry it was clear that we should avoid this big change that tmcw did so I just merged my version with tmcw's version for a temporary solution
18:19:24 <ppawel> for me the most important next step would be to keep cleaning up all the pages that are linked from Develop
18:20:25 <ppawel> optionally I had an idea to organize dev documentation better using the navbox template so there would be a navigation box at the bottom of each 'official' page, like so... http://en.wikipedia.org/wiki/Template:HBONetwork_Series
18:20:52 <ppawel> I think that would tighten the whole structure a little, also maybe help with content de-duplication
18:21:36 <ppawel> plus there was already a question about the 'architecture diagram'... http://wiki.openstreetmap.org/wiki/Talk:Develop#Recent_redesign
18:22:00 <ppawel> would be nice to have something simple in place of this old and complicated one
18:23:08 <ppawel> and one last thing is that I think it would be good to start a landing page for osm.org-specific development as there is no such page right now (except /Components which is a bit dated)
18:23:38 <zere> i'm not sure it's possible to have something simple which explains something so complicated. i'd love to be proven wrong, but i think we'd need to show less information.
18:23:51 <ppawel> I think that would basically be a page with "How the pieces fit together" paragraph that tmcw wrote plus further links and ways to get involved in osm.org
18:24:58 <ppawel> zere, yes I agree... looking at http://wiki.openstreetmap.org/wiki/File:OSM_Components.png - there is not much that can be removed actually to simplify...
18:25:12 <ppawel> but perhaps some face lift to improve the presentation of this would help
18:26:15 <zere> do we want to gather together some of the content that should be "avoided" as a "big change" and start to (perhaps temporarily) host that somewhere else?
18:26:15 <ppawel> oh and the really-one-last-thing on this topic is that I think the "Developers" link should be on the wiki sidebar
18:26:27 <ppawel> (it is not editable)
18:27:42 <ppawel> zere, do you mean the 'curated site' as discussed last week?
18:29:05 <zere> possibly. i'm of that opinion, and it seems that tmcw is leaning that way too. i'm just not convinced that the wiki is the best place for a lot of this stuff...
18:30:20 <zere> as a thought experiment - let's assume we didn't have a wiki, and we were documenting all this from scratch. what would the site need to look like in order to really help people coming to it with a variety of levels of experience?
18:30:51 <zere> i'm not in any way a web designer, but i have the feeling there must be common "patterns" for this kind of educational site?
18:31:45 <ppawel> I am not against this kind of thing but I would rather work on the 'hard' content like improving the rails port documentation or the architecture diagram
18:31:57 <ppawel> not sure to what level of detail you would like to go with such curated site
18:32:11 <ppawel> at some point I guess there would need to be a link to wiki 'for more details'?
18:40:03 <zere> i think so, yes. it seems to me it would be better to leave most of the detailed documentation to the projects' own sites - on the wiki or wherever
18:40:58 <zere> but the high (and maybe medium) level documentation would seem better kept on a site which could be completely designed to cater for vistors' needs.
18:41:07 <zere> tmcw: any thoughts on this?
18:41:44 <ppawel> yeah that makes sense
18:42:43 <tmcw> Er, not super-interested in working on this right now. There was potential low-hanging fruit of making the wiki better, but that's not looking likely with how the wiki is written/curated/managed/talked about.
18:42:54 <tmcw> As before, yeah, any effort in the near-term is on learnosm
18:44:22 <tmcw> So, the wiki will remain being relatively inaccessibly-written technical documentation until there's time to write something that replaces it for the 80% of users who are not looking for osm2pgsql secret codes.
18:47:40 <ppawel> for me more important is the up-to-date content, not the more accessible form since if you are a developer you will manage to understand even when there are problems with commas... at least that's true for the 'hard' content, the abstract/general stuff could be more polished I agree
18:48:13 <ppawel> so it looks like those are two rather separate issues - technical docs on the wiki (updating, structuring) and the 'nice' site
18:48:37 <tmcw> So indeed, I'm more or less abandoning the wiki because of the general culture.
18:49:33 <tmcw> That said, I think it could have been better documentation for everyone if there wasn't a majority of people who agreed on keeping it technical, comprehensive, and poorly-written.
18:50:16 <tmcw> But since that's the case, I won't try to go against the flow.
18:50:45 <ppawel> like zere said at the beginning, this isn't simple stuff so I don't see how can you make it user-friendly enough so someone like you will like it AND maintain the level of details
18:50:54 <ppawel> at least not without an army of technical writers...
18:51:27 <tmcw> Welp, anyway, we disagree, so that's that.
18:53:49 <zere> i think we're kind-of agreeing - documentation for technical users looks a lot different from documentation for the other "80%". in my opinion it makes sense to separate them, otherwise (as has happened many times) the technical documentation bleeds into the "80%" documentation and ruins it.
18:54:26 <zere> the related issue, which ppawel is talking about, is whether the technical "20%" documentation is adequate and up-to-date. and in many cases it's not.
18:54:35 <zere> i blame the wiki, but that's just me ;-)
18:55:40 <zere> a more interesting question is: what can we *do* about it? tmcw is going to work on learnosm, which is great. so that leaves making the technical documentation better (and liberally linking to content on learnosm for "introductory" material)
18:57:43 <apmon_> Is it possible to speak to the "target audience" and see where they actually had problems and were confused?
18:58:14 <apmon_> If we can get a list of concrete issues people had trouble with to begin with, it might make it easier to decide what needs including and how prominent each part needs to be
18:58:39 <ppawel> oh I think there is plenty of work to do even without doing this kind of research...
18:58:43 <ppawel> some issues are rather obvious
18:59:05 <ppawel> http://wiki.openstreetmap.org/wiki/Component_Overview talking about osmarender for example
18:59:16 <ppawel> and openlayers etc. etc.
19:00:47 <ppawel> there is also some technical content here - http://wiki.openstreetmap.org/wiki/Category:Suggested_merges
19:01:11 <tmcw> zere: learnosm is one piece of the puzzle, after there's better other material for what osm is, then it'll link to something like a one or two page site for people who want to get involved, similar to https://www.mozilla.org/en-US/contribute/
19:02:46 <zere> indeed, most of the existing documentation for OSM is in varying degrees inaccurate or out-of-date. there's a mountain of potential improvements and we can definitely start on multiple fronts at once.
19:04:07 <zere> research like apmon_ is suggesting might be useful to target the most painful of the steep learning curves. or, at least, some input. i know i've been steeped in this so long that it's difficult to force myself to forget for long enough to evaluate the current documentation situation.
19:05:03 <apmon_> usability research for technical documentation... ;-)
19:05:50 <zere> on a completely different subject: the next two EWG meetings would be the 24th and 31st. these aren't great days for me, and i'm guessing other people might have stuff scheduled for then as well. i propose that the next meeting be on the 7th jan 2013.
19:05:59 <ppawel> perhaps some kind of todo for this process would be good...? like a simple page on the wiki for coordination
19:06:33 <zere> ppawel: sure, why not? unless it gets out of date, of course ;-)
19:06:42 <ppawel> I'm sure it will...
19:06:47 <apmon_> Yes, I'll be out over the Atlantic on the 24th, so I won't make it then. Not sure about the 31st.
19:07:15 <apmon_> equally on a different topic. How did hackweekend go?
19:07:29 <apmon_> Is the notes branch closer to deployment?
19:07:29 <ppawel> at the end of the day I think it is doable to whip the docs into shape but people just need to do it...
19:08:02 <ppawel> and after subscribing to bunch of technical pages on the wiki I have not seen any updates in the past week
19:08:04 <apmon_> Can we still complete that top ten task before the end of the year?
19:10:07 <zere> apmon_: work was definitely done, but i'm not sure what the final status was. i was only able to attend part of the weekend.
19:10:51 <zere> ok, given lack of complaint - i'll schedule the next formal meeting for the 7th. of course, feel free to have informal meetings whenever suits ;-)
19:10:54 <zere> #endmeeting