I'm curious, how they write internal-facing documentation and how that effects the development experience for new github engineers.
Source diving through open source libraries, I've often wished for a "spelunker's guide": a text file laying out where things were and what I should read first to build a mental model I could use in understanding the rest of the source. I'm currently trying to figure out what the best way is for someone to write a spelunker's guide, especially if they've forgotten what it's like to be a beginner.
> I'm curious, how they write internal-facing documentation and how that effects the development experience for new github engineers.
I wish I could show up a sample, but I can't, because it's internal. ;)
Honestly, I think a lot of the engineering documentation started organically. When you have a small team working on a feature, it's difficult to scale explanations to the rest of the company. One day someone sits down and starts writing all their thoughts out in Markdown, and just checks it into a docs folder. That's it. It's easy-to-read, short on code, and usually full of ASCII, like this: https://i.imgur.com/KTbyhyq.png
Writing documentation is the best way to get outside contributors involved with minimal investment on your part. It also forces you to try and explain what you've built.
If you can't pretend to go back and look at things like a beginner, grab someone unfamiliar with the project, and have them describe to you what they would expect, and how they think they should proceed. They may be able to provide you with insights on what needs to be described.
Source diving through open source libraries, I've often wished for a "spelunker's guide": a text file laying out where things were and what I should read first to build a mental model I could use in understanding the rest of the source. I'm currently trying to figure out what the best way is for someone to write a spelunker's guide, especially if they've forgotten what it's like to be a beginner.