We welcome contributions (Pull Requests)!
We're using Github to write this guide as it's more likely to persist longer and allows for other people to discuss and contribute changes. It's a relatively new style of writing that most of us don't have experience with, so we're all experimenting on this together!
A few tips on making good PRs:
We acknowledge that there is no advice that'll work for everyone, and different people will find different tips helpful - all advice is subjective. Often advice is given as if it was objective ("you should do this", "if you want to be successful then this is best way", etc) and this guide explicitly tries to avoid this kind of tone.
It's important that readers of this guide know that there are many paths to successful internship search, and many ways of defining a successful internship search.
Therefore, when contributing please avoid words like 'should', and be aware of your tone (you provide suggestions, not sources of truth). It can be helpful to explicitly call out situations where different people will find different things helpful, to help the reader understand that it's expected that they pick and choose what works for them.
We also would like to strike a balance between accurate/complete information, and trying not to overwhelm the reader with too many things they need to do, or technicalities. There are going to be tradeoffs sometimes, but they're not completely at odds. If a section or file is growing too big with information, it might be worth factoring the details out into a separate section or file. Just like when a function grows too big!
Emphasis markers help the reader focus on the key point of a section.
Blockquotes allow you to reduce emphasis on personal stories and more advanced details.
If you have something to add in a section, please read the whole section over and check that:
- The text still follows a reasonable progression
- The tone is similar
- There are no major contradictions with what's already there (it'd confuse the reader!)
That doesn't mean we don't want you to disagree with us! We just want to keep the guide as consistent as possible. Ways to disagree productively include opening an issue with proposed changes first, or writing the alternative point of view as a personal story.
Like a regular codebase, there's going to be some artifacts in the writing that we'll want to "refactor" over time. As the number of contributors increase, the usage of the pronoun "I" (which is still pretty common in the docs) might get confusing. There's still some of that left, which we should remove over time. Add your name if you'd like to put your own story or opinion as advice.
Website generated by Ronak Shah with mkDocs
You can run a preview version of the website on your local computer from source files (contents of doc/ directory). First install mkDocs:
pip install --upgrade pip
pip install mkdocs
and run mkdocs serve, which display the website at localhost:8000 and will auto-update when files change.
Deploying to the gh-pages branch to update is done via mkdocs gh-deploy (though the maintainers of the repo will take care of doing that).