New learnosm contributor's guide

[jmarlena]

Addresses need for expanded new contributor's guide in #329. This PR is taking cues from @Nick-Tallguy's guide in issues https://github.com/Nick-Tallguy/Testing_learnosm/issues/7 and https://github.com/Nick-Tallguy/Testing_learnosm/issues/8 as well as the discussion in #329.

Status: This PR still needs some work. :)

[SteveBower]

Hi Jessica @jmarlena ,
I've been working with @Nick-Tallguy and the Training Working Group, and had volunteered to help revise the LearnOSM Contributor's documentation. So you & I have done some work in parallel - I should have contributed here sooner but was slammed with other stuff. I'm fairly new to GitHub and LearnOSM development, so I think I can approach the documentation from a newbie’s perspective. I've reviewed all the existing documentation (contribute.md, your 'docs' files, Nick's repo pages, wiki, GitHub issues).

I like what you kicked off in the 'docs' folder, but building on #329 and other discussions, I think there are 2 key decisions to make before fully revising the Contributor's documentation:

1. Where should the documentation be hosted?
2. What content and how organized (outline)?

As to where to host it, that may be driven by @althio 's suggestion (and others) that it support translation into other languages. That seems a good goal to me. In that case, it probably makes sense to host it as another Guide on LearnOSM, with multiple modules (web pages), to take advantage of the existing translations workflow. Otherwise, a series of pages in "docs" would work fine, under a home page with the overall outliine/structure.

As for the content, I drafted an outline in a Google doc to make it easy for everyone to contribute. If you and others think this is a good way to organize the overall content, then feel free to add comments and edit the document. The audience would be both newbies and those familier with the technologies. I've tried to account for all existing documentation.

I'm curious to know what you think & how this fits with your vision, of course. Looking forward to collaborating.

[Nick-Tallguy]

Hi,

Just a quick note about translations - I can submit any of the guides
for translation - so any or all of the documents in this folder:

https://github.com/hotosm/learnosm/tree/gh-pages/docs

can be submitted to Transifex for translation. Without a little more
research, I'm not sure how they would be displayed on the site, but I
don't anticipate it would be any great problem.

Regards

Nick

On 29/03/16 16:14, Steve Bower wrote:

Hi Jessica @jmarlena https://github.com/jmarlena ,
I've been working with @Nick-Tallguy https://github.com/Nick-Tallguy
and the Training Working Group, and had volunteered to help revise the
LearnOSM Contributor's documentation. So you & I have done some work
in parallel - I should have contributed here sooner but was slammed
with other stuff. I'm fairly new to GitHub and LearnOSM development,
so I think I can approach the documentation from a newbie’s
perspective. I've reviewed all the existing documentation
(contribute.md, your 'docs' files, Nick's repo pages, wiki, GitHub
issues).

I like what you kicked off in the 'docs' folder, but building on #329
#329 and other discussions,
I think there are 2 key decisions to make before fully revising the
Contributor's documentation:

1. Where should the documentation be hosted?
2. What content and how organized (outline)?

As to where to host it, that may be driven by @althio
https://github.com/althio 's suggestion (and others) that it support
translation into other languages. That seems a good goal to me. In
that case, it probably makes sense to host it as another Guide on
LearnOSM, with multiple modules (web pages), to take advantage of the
existing translations workflow. Otherwise, a series of pages in "docs"
would work fine, under a home page with the overall outliine/structure.

As for the content, I drafted an outline in a Google doc
https://docs.google.com/document/d/1v8G4MwFqyjpZSUTaYn1OgPrfgJkoHdhJBmsorb7HY9E/edit?usp=sharing
to make it easy for everyone to contribute. If you and others think
this is a good way to organize the overall content, then feel free to
add comments and edit the document. The audience would be both newbies
and those familier with the technologies. I've tried to account for
all existing documentation.

I'm curious to know what you think & how this fits with your vision,
of course. Looking forward to collaborating.

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#494 (comment)

Nick

Volunteer 'Tallguy' for
https://wiki.openstreetmap.org/wiki/Humanitarian_OSM_Team

http://www.openstreetmap.org/user/Tallguy

[jmarlena]

Hey Steve!

Where should the documentation be hosted?
I think you've made some great points! It totally makes sense to have the
contribution guide as a part of the site so that it can be translated
easily. I think putting it on LearnOSM in its own guide is an excellent
idea.

What content and how organized (outline)?

I added some comments to this outline.

Thanks for continuing the conversation here!

Best,

Jessica

On Tue, Mar 29, 2016 at 8:14 AM, Steve Bower [email protected]
wrote:

Hi Jessica @jmarlena https://github.com/jmarlena ,
I've been working with @Nick-Tallguy https://github.com/Nick-Tallguy
and the Training Working Group, and had volunteered to help revise the
LearnOSM Contributor's documentation. So you & I have done some work in
parallel - I should have contributed here sooner but was slammed with other
stuff. I'm fairly new to GitHub and LearnOSM development, so I think I can
approach the documentation from a newbie’s perspective. I've reviewed all
the existing documentation (contribute.md, your 'docs' files, Nick's repo
pages, wiki, GitHub issues).

I like what you kicked off in the 'docs' folder, but building on #329
#329 and other discussions, I
think there are 2 key decisions to make before fully revising the
Contributor's documentation:

1. Where should the documentation be hosted?
2. What content and how organized (outline)?

As to where to host it, that may be driven by @althio
https://github.com/althio 's suggestion (and others) that it support
translation into other languages. That seems a good goal to me. In that
case, it probably makes sense to host it as another Guide on LearnOSM, with
multiple modules (web pages), to take advantage of the existing
translations workflow. Otherwise, a series of pages in "docs" would work
fine, under a home page with the overall outliine/structure.

As for the content, I drafted an outline in a Google doc
https://docs.google.com/document/d/1v8G4MwFqyjpZSUTaYn1OgPrfgJkoHdhJBmsorb7HY9E/edit?usp=sharing
to make it easy for everyone to contribute. If you and others think this is
a good way to organize the overall content, then feel free to add comments
and edit the document. The audience would be both newbies and those
familier with the technologies. I've tried to account for all existing
documentation.

I'm curious to know what you think & how this fits with your vision, of
course. Looking forward to collaborating.

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#494 (comment)

*Jessica M. Canepa *
@jmarlena_canepa https://twitter.com/jmarlena_canepa | (971) 313.2017

[SteveBower]

Thanks Jessica. I tried to include everything relevant that I'm aware of in the outline. I'm not sure what all would go under "Advanced Architecture", because I don't know the details of LearnOSM's architecture. If you or others have any thoughts on what to include there, add them to the outline.

Once there's general agreement on the outline, we can decide how to divide it into separate pages (LearnOSM modules). Then create them and integrate what you've written so far (I've written some too) - if that all sounds good.

~~Steve

[jmarlena]

Hey Steve,

Maybe this outline can be reviewed at the next training working group
meeting and then we can break this up as needed.

I think I will do a little research on the learnosm' s current architecture
and try to share some of my findings by this upcoming Friday, 4/8/16.

-Jessica

On Sat, Apr 2, 2016 at 2:55 PM, Steve Bower [email protected]
wrote:

Thanks Jessica. I tried to include everything relevant that I'm aware of
in the outline
https://docs.google.com/document/d/1v8G4MwFqyjpZSUTaYn1OgPrfgJkoHdhJBmsorb7HY9E/edit.
I'm not sure what all would go under "Advanced Architecture", because I
don't know the details of LearnOSM's architecture. If you or others have
any thoughts on what to include there, add them to the outline.

Once there's general agreement on the outline, we can decide how to divide
it into separate pages (LearnOSM modules). Then create them and integrate
what you've written so far (I've written some too) - if that all sounds
good.

~~Steve

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#494 (comment)

*Jessica M. Canepa *
@jmarlena_canepa https://twitter.com/jmarlena_canepa | (971) 313.2017

[SteveBower]

Hi Jessica - that sounds good. I would definitely like some feedback on it. I just added everything that would have helped me starting out.

[jmarlena]

@SteveBower I realize I am not sure what you mean by the site's architecture. Do you mean information architecture or the software used to run and build the site?

As far as how the site is created, it is powered by Jekyll and GitHub Pages. It looks like it's running on an older version of Jekyll still.

So looking at the site's source files it looks like there's a couple places that could use some updates, especially since GitHub Pages recently updated to Jekyll 3.0:

• gemfile and gemfile.lock
• possibly config.yml if there are some other breaking changes I couldn't find

I don't think that there should be any problems yet with Jekyll being slightly out of date.

[SteveBower]

@jmarlena - By 'architecture' I mean an overview of the main system/software components and how they interact. I guess it's limited to Jekyll and GitHub pages, but I don't know (and haven't researched), for example, how the LearnOSM home page and navigation panels are generated. Those are more advanced topics than simply updating the content of existing LearnOSM modules. So 'architecture' may not be the best term. But the topic of understanding how to contribute to those more advanced aspects of LearnOSM would be good to cover, at least at a high level.

Sorry for my delayed response. I'm subscribed to receive email notifications for this issue but do not receive them - I don't know why, I've double-checked my settings. Let me know if you have any hints on that.

[SteveBower]

Hi @jmarlena - I'd like to jumpstart this process of creating a new LearnOSM guide on "Contributing to LearnOSM". In April you suggested reviewing my draft outline in a Training Working Group meeting, then proceed from there - but that never happened. We have a Training Working Group meeting today, 1900 UTC (3:00pm US Eastern), if you want to participate. In any case, let me know if you'd still like to work on this. I think the outline is a good basis for creating a new LearnOSM guide - it just needs to be organized into modules (separate web pages). It would be great to collaborate on that - I would want at least a good review by you & Nick, since you know the tools & process better than me. Thanks.

(Again, I'm signed up to receive notifications for this issue, but do not receive them - so I'll keep an eye on it but forgive me if I don't respond right away.)