Improve how our documentation supports contributors new to git

[clausmullie]

Some of the community members that the Foundation for Public Code interacts with are new to git - for example policy makers.

Our contribute as an individual includes some basic introduction for users new to github.

However, we also have activities/trainings/ which has some great content on learning git and navigating the github interface. This is where we direct new staff as well.

I propose to:

• add in a line on contribute as an individual inviting users new to git to visit our activities/trainings/
• move any non-repo speciifc explanatory content from contribute as an individual to activities/trainings/, with clear invitations and hyperlinks
• continue to add new resources and guides to activities/trainings/

This will reduce the amount of duplication and maintenance (we now have two places that explain how to write issues) and centralise resources (we don't inform staff about our use of github flow or link to the markdown cheatsheet), and encourage individual contributors new to git to a github training.

[clausmullie]

Linked to this, we may also want to link to activities/trainings/ from our for/staff contributing guide. As well as move the training type material there to the activities/trainings/ index.

Centralising all our trainings in one place and linking to this from various entry points will make it easier to oversee and maintain, and provide a richer set of resources to the various different users.

[clausmullie]

To enumerate further on this issue:

We currently have relatively detailed how to staff and individual contributor pages, with a relatively light training page. All three contain some information about using git, GitHub, and how we work with documentation. The advantage is that this can be written differently for each angle. Disadvantage is that we have some information that is in one place but not the other (but is useful for all angles) and duplicate some information. This makes this easier to personalise, but harder to maintain.

My proposal is to centralise more things in training, and link to the training directory from the other pages. My reasoning is that as an open organisation, a) our resources shouldn't need that much personalisation and b) we want individual contributors to be able to contribute at the same level as staff, should they choose to want to do so. This will also cut the complexity of trying to explain git, GitHub and our way of working in contributing.md (which we currently attempt, but also briefly so as to not overload), link individual contributors to training so they can decide to read more informative resources based on their current experience level. It also allows us to work on adding more trainings, such as future how we work sessions or other best practice/learning on how to work effectively in the open, and have these available to everyone. trainings will also become increasingly fleshed out as we work towards 'online training resources to promote awareness in the ecosystem' as stated in the roadmap.

[ericherman]

I would welcome this reworking of that content.

[Ainali]

I like your suggestions @clausmullie!

[clausmullie]

Note: both the standard and jekyll theme repo's have quite nice (identical) contributing.md files.

This issue could potentially be reopened to: a) scan for what can be reused from there to improve the one on about b) whether we want to have one 'main' file on about, which all the others link to, before going on to repo specific instructions? this would dedupe somewhat and maximise the investments we make to improve the one on about (I think I've seen this done in other organizaitons) c) scan for other repo's that don't have a contributing.md file (eg projects)

What is your sense on this @Ainali ?

[Ainali]

I think all three of your suggestions are good, but rather than reopening this issue, I would like to see separate new issues for these.