https://alphagov.github.io/tech-docs-manual/#show-contribution-banner

I believe that we should also cover what we mean with "well defined tasks" by providing examples, it's important that juniors have an understanding of what is a "well defined task" in order for them to know if the task is up to the standards before they pick it up and ending in a rabbit hole.
This is also valuable for developers (and seniors) who need to write "well defined tasks", by having examples it will gives us a standard on everyone's expectations of a "well defined task".

https://blog.github.com/2018-04-19-introducing-github-learning-lab/

http://softwareleadweekly.com/

People mention this every now and again, and each time I think "+1, this is a really good resource"

so maybe that's a sign it should be part of the learning pathway (although I'm not sure exactly where).

It's useful even if you're not in a tech lead role.

http://benchmarksgame.alioth.debian.org/u64q/compare.php?lang=yarv&lang2=go (snapshot)

This is linked from the ruby resource list.

This will stop me raising so many pull requests with typos in.

Vale does a spell check, but also checks for more general problems with the writing, like use of passive voice. We're using it already for the GOV.UK developer docs.

Competency documents should link to

• Resource documents
• GDS way
• Service manual
• Anything officially maintained by GDS

We think this will make everything easier to review and maintain.

Currently we deploy the site by running cf push

Ideally we want it to autodeploy so that you don't need a PaaS account to contribute and anyone at GDS can merge a PR.

The current career path was written at a time when we didn't have apprentices, and the learning resources have been built up around it.

We should look at how we can integrate this into the existing competencies, so that it's clearer how to move from apprentice to junior.

This is a good resource https://github.com/cxxr/better-java

We had a guide like this on the alphagov wiki. I transfered it to https://sites.google.com/a/digital.cabinet-office.gov.uk/gds-technology/learning-and-development/learning-resources/learning-python

But it should still be there in markdown format.

More recently Kenneth Reitz started http://docs.python-guide.org/en/latest/ which is great for somebody starting out in python.

The tech docs gem has a mechanism for marking when a page was last reviewed: alphagov/tech-docs-gem#12

We should enable this so that users can see when information is outdated.

Before we invite the wider technology community to contribute we'd like to establish some patterns and structure for this repo.

Questions/issues:

• are 'guides' the right name?

User stories:

• Be able to find the right learning when they know what they want to learn
• be able to browse the things which they could learn for inspiration
• keep individual names private (ie, list of mentors etc should be stored elsewhere) - we intend to make this repo public

Acceptance criteria

• we have a CONTRIBUTING.md setting out clearly how people should contribute

testing testing testing

Indicate that this is currently for GDS use, not wider government (at least the career path section of it), although external contributions are still welcome.

This is something that's been proposed for the GDS way and we should follow suit if that changes.

Google have published their Site Reliability Engineering book under Creative Commons. It has some really good nuggets in it.

https://landing.google.com/sre/book/index.html

The latest version of the tech docs gem has a search feature. We should use it 🔍

https://github.com/alphagov/tech-docs-gem/blob/master/CHANGELOG.md#150

We think "guide" is misleading because we actually want to minimise the amount of content we have to maintain.

What we actually want is a list of resources. We can make a resources directory, move things over and see whats left in the guides bit.

Maybe we should set up some CI running something like this https://www.npmjs.com/package/markdown-link-check

There was some stuff on the wiki wiki (which no longer exists) that I migrated to the new wiki last year:
https://sites.google.com/a/digital.cabinet-office.gov.uk/gds-technology/learning-and-development/learning-resources

Let's review the links and either delete/consolidate.

There are also various docs in google drive that we could incorporate here.

I noticed our testing guides and competencies are a bit fragmented at the moment.

We have one competency/guide linked from mid-level: Validating solutions to problems by using appropriate testing

• This is not split by level
• It links to a non existent TDD guide
• It links to a non existent Performance testing guide
• It links to per language guides which also don't exist

We also have another competency linked from junior-level: Testing

• This is split by level
• There are external resource

I suggest we merge "Using appropriate testing" into "Testing" and create a series of guides associated with that competency, starting with TDD.

Testing guides should be reachable from the testing competency and from other guides, such as the ruby language guide.

suggested by @46bit

• Should we put something together specifically about experiences in GDS?
• Are there other perspectives we can share? Eg https://leanpub.com/talking-with-tech-leads

We're using the ruby buildpack when deploying to PaaS, but we don't actually need it.

There is a static files one we can use instead - example here: https://github.com/alphagov/registers-tech-docs/blob/master/manifest.yml

https://sites.google.com/a/digital.cabinet-office.gov.uk/gds/communities-of-practice/back-end-development links to a document from 2016. We should incorporate the resources it links to, and link to this instead.

The women's network have put together a bunch of resources on career progression. This is not specific to the tech community, but it is relevant to GDS/cabinet office staff and seems like something we might want to link to.

https://sites.google.com/a/digital.cabinet-office.gov.uk/gds/cross-gds-social/women-in-gds/resources-for-you

Not all tech leads are senior devs and not all senior devs are tech leads
How can we help people transition into a tech lead role as mid level or senior? What competencies should people in this situation focus on?

Currently, the career path pages link have a list of statements, which differ across levels. Then they link through to competency pages which have sections for what you should know at each level.

This would be clearer if we reviewed those statements, and changed the link text to use the title of the competency statement.

So instead of

Best practices in [testing](/career-path/competencies/using-appropriate-testing-to-ensure-software-quality.md#junior-level)

We'd say

[Using apprpriate testing to ensure software quality: best practices ...](/career-path/competencies/using-appropriate-testing-to-ensure-software-quality.md#junior-level)

This should probably be both a competency statement and possibly one or more guides. The competency statement should list out the competencies at each level of the career path.

https://github.com/alphagov/tech-docs-template

Problem

When we moved to the tech docs template, we directly translated all the markdown files we had into pages in the tech docs.

Because we've kept the existing structure, parts of the site are disconnected from others. For example, if you're on a competency page there is no way to navigate back up to the career path, and to other competencies, other than inline links and the back button.

But we can do stuff in the tech docs that we couldn't do with plain markdown, and we can do more to show users where they are in the structure of the site. See #92 for more info.

Task

I think we should review the overall information architecture and make some recommendations for future changes (I'm happy to help out with this).

We have a guide for Pair/mob programming, and a competency Taking the lead in a pairing situation, both linked to from different roles.

I feel the competency file already includes the guide to pairing - maybe we only need one file?

There is a tech community wiki here https://sites.google.com/a/digital.cabinet-office.gov.uk/gds-technology/roles/tech-lead

It's quite out of date and may go away. But it has some interesting content around the role of the tech lead.

This issue is to consider whether we want to absorb this into the learning pathways, and if so how best to do it.

• Ask some tech leads whether this still reflects reality (it's from 2014)
• Decide which parts are useful to prospective or current tech leads
• Work out where it fits into the project

Some notes from some conversations, with links to interesting resources:

• https://microcorruption.com/about if you're interested in some of the lower level buffer overrun type stuff.
• http://cryptopals.com/ is fun for cryptanalysis stuff.
• we've used https://github.com/OWASP/railsgoat for security workshops
• bandit levels from http://overthewire.org/wargames/
• https://alf.nu/alert1 - really good for understanding xss and injection attacks
• challenges on https://en.wikipedia.org/wiki/HackThisSite . It's pretty good at giving a step by step intro (or at least I felt it was back in the day).

I think we can improve the navigation structure by updating to the latest version of the tech docs template

• Currently when you go to "how to contribute" it opens up a section of the main page, which is just a link to another page, but that page doesn't itself show up in the navigation

• The competency and guide pages themselves are not visible in the main nav, and have their own sidebars

The new collapsable navigation items should help with this. See https://github.com/alphagov/tech-docs-gem/blob/master/CHANGELOG.md#140

Blog post: https://codeascraft.com/2016/11/17/debriefing-facilitation-guide/

Guide: https://extfiles.etsy.com/DebriefingFacilitationGuide.pdf

We now have https://github.com/alphagov/gds-tech which documents how we do stuff at GDS, including particular technologies and software we've chosen to use.

I think some of this gives specific examples of things we talk about in relation to competencies. Maybe we could tie it all together.

For example:

• A junior (role) https://github.com/alphagov/gds-tech-learning-pathway/blob/2e12425294b8f34d6843ec3264bbb5ec023329fe/career-path/junior.md
• regularly demonstrates ability in using version control and editors (competency)
• Here's what you should be able to do in git and why: https://github.com/alphagov/gds-tech-learning-pathway/blob/2e12425294b8f34d6843ec3264bbb5ec023329fe/guides/version-control.md
• At GDS, here's how we use use version control and code in the open:
  https://github.com/alphagov/gds-tech/blob/master/source-code.md

Before we moved to the tech docs template, I set up a tool called awesome_bot to check for broken links.

I thought I could just continue scrape the markdown files for URLs and keep using the same tool, which works for monitoring external links.

However, this doesn't work for detecting internal broken links, because it tries to find them in the git repo instead of resolving them against a rendered page.

We should just disable internal link checking until we have a better solution. One way of doing it might be to build the docs on CI, serve them, and use that as a base for relative URLs with awesome_bot.

This is a duplicate of #25

I'm just creating this issue to include it in https://github.com/alphagov/gds-tech-learning-pathway/projects/1

http://www.alexandra-hill.com/2018/06/25/the-art-of-giving-and-receiving-code-reviews/

Comprehensive resource covering design, architecture, interpersonal skills, career development:

https://github.com/mr-mig/every-programmer-should-know

http://portal.netobjectives.com/pages/roles/developer-role/

https://methods.18f.gov/

https://github.com/dkhamsing/awesome_bot#danger