diff --git a/meta/style-guide/README.md b/meta/style-guide/README.md new file mode 100644 index 0000000..1279493 --- /dev/null +++ b/meta/style-guide/README.md @@ -0,0 +1,171 @@ +# Evergreen Style Guide + +This document serves to provide a set of guidelines for how to write good +documentation for Evergreen. This guide is less focused on the content and +more focused on the style and structure of the documentation. + +## People + +Whenever referring to someone in Evergreen, if they are a member of our +team and have an entry in [purduehackers/dark-forest](https://github.com/purduehackers/dark-forest) +then you should ALWAYS use the following format to refer to them: + +✅ Correct + +```markdown +[@rayhanadev](https://github.com/purduehackers/dark-forest/blob/main/people/organizers/rayhanadev.md) +``` + +You should never not link to someone in dark-forest if they have an entry there +and you should never refer to someone by a handle besides their dark-forest +handle. + +❌ Incorrect + +```markdown +@rayhanadev +@someotherhandleforray +[Ray](https://github.com/purduehackers/dark-forest/blob/main/people/organizers/rayhanadev.md) +``` + +## Linking + +When linking to other pages in the Evergreen documentation, you should always +use absolute links from the root of the repository. This is to ensure that +links do not break _toooooo_ hard when the documentation is moved around. + +✅ Correct + +```markdown +[Hack Bishops](/meta/structure/bishops.md) +``` + +❌ Incorrect + +```markdown +[Hack Bishops](../structure/bishops.md) +[Hack Bishops](structure/bishops.md) +``` + +You should also always use the title of the page as the text for the link +if it is a page in the Evergreen documentation. + +✅ Correct + +```markdown +[Hack Bishops](/meta/structure/bishops.md) +``` + +❌ Incorrect + +```markdown +[The Bishops Page](/meta/structure/bishops.md) +``` + +## Files and Folders + +As long as it generally makes sense, you should always feel free to create +new files and folders in the Evergreen repository. Some general tips for when +to create new files and folders: + +- If a page is getting too long, consider splitting it into multiple pages +- If a page is getting too complex, consider splitting it into multiple pages +- If aspects of a page can stand alone, consider splitting them into multiple pages +- If you are working on a project, consider creating a folder for that project + +✅ Correct + +```plaintext +/meta/structure/bishops.md +/meta/structure/divisons.md +/meta/structure/hierarchy.md +/meta/structure/roles.md +``` + +❌ Incorrect + +```plaintext +/meta/structure.md +/meta/roles-and-divisons.md +``` + +## README.md vs Other Files + +It is generally recommended to use `/README.md` when creating a +new project in Evergreen vs. adding a `.md` file. This is because +the README file is the first file that is displayed when you navigate to a +folder in GitHub and it is generally the first file that people will look at +when they are looking at a project. + +You should create `.md` files within a specific project folder for more +topics that are related to that project. A good example of this is the [Hack Night](/events/hack-night/README.md) +folder in the Evergreen repository. + +✅ Correct + +```plaintext +events/hack-night +├── README.md +├── attendance.md +├── badges.md +└── circles + ├── README.md + ├── data-science.md + └── systems.md +``` + +❌ Incorrect + +```plaintext +events +└── hack-night.md + +events/hack-night +├── hack-night.md +└── circles + └── circles.md +``` + +## Attribution + +You should never write an attribution in Evergreen. This philosophy is because +we use Git/Github to track changes to the documentation and it is easy to see +who wrote what and when and get a clearer picture of the document's history. +Adding an attribution to a page is redundant and adds complexity to what needs +to be updated in documentation, therefore it is preferred that you do not add +attributions to pages. + +✅ Correct + +```markdown +# Hack Bishops +``` + +❌ Incorrect + +```markdown +# Hack Bishops + +Written by @rayhanadev +Last updated by @rayhanadev +``` + +## Images + +When adding images to the Evergreen documentation, you should always add them +to a folder relative to the project. For example, if you are adding an image to +the [Hack Night](/events/hack-night/README.md) folder, you should add the image +to the `events/hack-night/images` folder, even if a subfolder is using the image. + +✅ Correct + +```plaintext +![Hack Night](/events/hack-night/images/hack-night.png) +``` + +❌ Incorrect + +```plaintext +![Hack Night](https://example.com/hack-night.png) +![Hack Night](/images/hack-night.png) +```