Guides & managing issues

[Nick-Tallguy]

We've spoken in the past about the need to make sure that we make it easier for someone new to learn how to help update LearnOSM.
I've also noticed that we have many issues that mention the same subject.

Just as a little trial, I've created:

• https://github.com/Nick-Tallguy/Testing_learnosm/issues/7
• https://github.com/Nick-Tallguy/Testing_learnosm/issues/8
• (Unfinished - still needs lots of work) https://github.com/Nick-Tallguy/Testing_learnosm/issues/9

They are in a temporary location, & I've created an issue label Guide to Updating this site in my temporary location.

The idea is;

1. Create a guide - long title that covers all of the likely search options - use copy & paste to transfer it from the temporary location into this repository.
2. Lock the guide (Owners & collaborators can unlock & amend it still, before locking)
3. Add the label Guide to Updating this site or whichever label we decide is appropriate.
4. Cross refer some of the long issues that the new guide is a summary of, and then close the long issue.
5. Link the guide to 'contributing.md'

As well as giving guidance to us mappers that are trying to learn how to update github, it may make managing the issues easier.

The wiki currently contains some information about updating the site, but the issues are searchable & can be kept as 'bite sized bits'.

Views, comments & criticism are all appreciated.

[althio]

@Nick-Tallguy
I agree this kind of documentation is needed.
It is more than useful to define a clean process, and share it with new and existing contributors.
I fully support this idea and your work so far.
Now on with the details and a few things I approve or disagree or do not understand.

+1 about the format with steps, screenshots.
It would be nice to have the actual content reviewed by someone not familiar with the tools.

I agree it is more clear to split the guides into different parts.
Building on your proposal, I have in mind maybe even more parts with the following structure:
0. account creation, install software, setup

1. sync main/fork/local before contributing
2. contribute (new branch in fork, local changes in new branch, sync branch to fork, pull request from fork to main repo)
   2+ [optional] rebase, squash, ...
3. text files, technical: filing, naming, front matter, markdown, links
   3+ text files, style: conventions and guidelines
4. image files, technical: filing, naming, size
   4+ image files, style: conventions and guidelines

You already provide in the current issue a lot of elements for 0-1-4, I think 2 is missing, 3 is scattered in different places. 2+/3+/4+ are not necessary but nice-to-have IMO.

I am not too happy with the long titles: IMO that is "entitling for the search engine" and it is almost as bad as "tagging for the renderer". ;) Joke aside, GitHub can search within issues, not only titles.
I am also divided about using issues for this purpose. I might be a little too rigorous but I think (locked) issues are not the right places to put documentation. But I like your general idea, and I like some details especially like cross referring the long issues.
So what and where?
I am inclined to say this should be available in an obvious place and... this should be available for translation.
So why not directly on LearnOSM website, and expand the Help/Contribute page to a small guide?

The important point is to put documentation about contributing in one place, complete, self-contained, well-structured.
Whatever the unique place, we should provide links to this documentation from:

• LearnOSM homepage
• LearnOSM Help/Contribute page (file contribute.md)
• README.md
• CONTRIBUTING.md
• one locked Github issue with redirection and cross-references between related issues.
• Github repo wiki
• wiki OSM-HOT

Over to you.

[jmarlena]

Hey @Nick-Tallguy & @althio! I really like where this is going. Following some of the best practices described in this guide I thought we could just add some files in a docs folder in the existing site and use a README.md file to let people navigate through. I started work on condensing your guide in docs folder files. I will try to have this better organized in the next week as my schedule lets up. We could link from the CONTRIBUTING.md to the docs' folder's README.md.

The links aren't working yet and I haven't adjusted the content yet but I started to create this: https://github.com/jmarlena/learnosm/tree/new-learnosm-contributors-guide/docs.

[SteveBower]

I suggest closing this issue, given its reference from #494

[Nick-Tallguy]

Text of message send to Training Working Group.

Hi,

At present anyone wishing to help with translating, or updating learnosm in some way may find the guidance in any one of a number of places;

1. From any of the pages on http://learnosm.org/en/ you can click on the pencil symbol top right and read contribute.md

2. contribute.md has a number of links;

   Send us feedback - email link to learnosm group

   Create a translation leads to CONTRIBUTING.md

   Improve Language leads to the issues list on Github - https://github.com/hotosm/learnosm/issues

   Report issues and contribute leads to https://github.com/hotosm/learnosm - basically the same as the above.

3. There is also a wiki on github with sections about images, style guides, how to write in markdown, explanation of how the site is organised, and several other guides.

4. There is a wiki on the staging site at https://github.com/Nick-Tallguy/Nick-Tallguy.github.io/wiki with Translator instructions for Transifex, interim guides, images (guide to requirements)

5. There is a folder at https://github.com/hotosm/learnosm/tree/gh-pages/docs which contains guides to contributing.

I propose to spend some time trying to tidy this up & consolidate it in one place. I have created an amended contribute.md file on the staging site at http://nick-tallguy.github.io/en/contribute/ and the links now lead to ;
email to group - unchanged from above
Help with translations - now leads to a holding module at http://nick-tallguy.github.io/en/contribute/translator/ - I intend to populate this guide with the info from the staging site wiki, and move the link on transifex so it points to the new guide
Improve Images - in your language! leading to http://nick-tallguy.github.io/en/contribute/translator-images/ - a new guide I have created for a translator wishing to upload localised images for their language - work in progress.
Report issues and contribute - unchanged.

As a result of this, learnosm has a category of 'contribute' which is containing the new guides, and I intend to expand this with the information from the existing guides, closing down the old guides and linking all to the new ones.

When you inspect any of the new guides on the staging site you will notice that the other contribute guides appear in the menu to the left. However they only appear in this menu if you are already looking at something in the 'contribute' section. I have deliberatly not created a chapter heading, which means they do not appear in the menu as a matter of course, but only when accessed off of the contribute page (from the pencil symbol on any page). I've probably not explained this very well, but if you click on buttons on the staging site whilst looking at the menu's you should get to understand what I'm explaining.

I'm adding discussion on this to #329 - please feel free to let me know your views on my proposal

Assuming this is going ahead, any help would be welcome!

Thanks for reading

Nick

[althio]

Good all around :)

Maybe one can try to structure the contribute chapter so that it can accommodate more in the future:

• contribute to LearnOSM
  • style
  • images
  • translation
• contribute to translations in OpenStreetMap projects
  • overview
  • editors:
    • iD
    • JOSM
    • Vespucci/...
  • wiki
  • ...