Create Style Guide #77
Conversation
| ✅ Correct | ||
|
|
||
| ```markdown | ||
| [@rayhanadev](https://github.com/purduehackers/dark-forest/blob/main/people/organizers/rayhanadev.md) |
There was a problem hiding this comment.
it's not abundantly clear from this where i get this username. should mention explicitly that the username should be pulled from dark-forest
| 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: |
There was a problem hiding this comment.
| 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: | |
| As long as it generally makes sense, you should always feel free to create | |
| new files and folders in the Evergreen repository. Some tips for when | |
| to create new files and folders: |
pedantic nit but you're using "generally" too much :P
| ❌ Incorrect | ||
|
|
||
| ```plaintext | ||
| /meta/structure.md | ||
| /meta/roles-and-divisons.md | ||
| ``` |
There was a problem hiding this comment.
This example is not communicated well in the above text. The above text says "feel free to create files, but split them out if they're too complex." The "feel free to create files" part confuses the rule. I think this rule should be simplified to something like: "Keep each page focused to one topic; do not make a file too broad or cover more than one specific topic"
|
|
||
| ## README.md vs Other Files | ||
|
|
||
| It is generally recommended to use `<project-name>/README.md` when creating a |
There was a problem hiding this comment.
| It is generally recommended to use `<project-name>/README.md` when creating a | |
| Use `<project-name>/README.md` when creating a |
| It is generally recommended to use `<project-name>/README.md` when creating a | ||
| new project in Evergreen vs. adding a `<project-name>.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 |
There was a problem hiding this comment.
| folder in GitHub and it is generally the first file that people will look at | |
| folder in GitHub and it is the first file that people will look at |
| ✅ 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 | ||
| ``` |
There was a problem hiding this comment.
These examples having slightly different file trees confuses the example. The point of this example is to illustrate using README.md over item.md, so the trees should be at parity in every way except for this.
| 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. |
There was a problem hiding this comment.
| 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. | |
| Do not write an attribution to an Evergreen document. We use Git/GitHub to track changes, including attribution. Adding your own attribution to a page is redundant and adds complexity. |
| 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. |
There was a problem hiding this comment.
The wording on this is confusing and creates lots of questions. What does "project" mean and what if you're not adding documentation for a project?
The subfolder part is confusing to me too. Where exactly should the image be added? What is considered a subfolder and not?
I think it's also worth adding more correct/incorrect examples to this rule's examples.
Closes #65