tags: Documentation and Standardization

General suggestions

• Example rendered pdf.
• Avoid first/second person tenses. Avoid starting and using sentences such as "I think", "I agree", "he said", etc…
• Avoid using #. Make sure there aren't any #s written in the Issue description.
• The issue description should be detailed. Ideally, someone who is outside of the project and the security review team should be able to understand the issues, merely by reading the issue description.
• Group issues together, whenever that's relevant. For example, if a certain gas optimization is relevant throughout the codebase, keep it as a single issue.
• Avoid screenshots. Prefer text whenever possible, for example, for code snippets, specification, etc.
• Consider minimizing code examples for the most relevant parts.
• Use permalinks for links to a hosted git source code (to specific commit hashes).
• Avoid raw links, i.e, prefer NoDelegateCall.sol#L18 instead of https://github.com/Uniswap/v3-core/blob/62d65bf88c4fb23671104c28f5bcae566274cb15/contracts/NoDelegateCall.sol#L18.
• Consider using diffs while making code recommendations.
• Use code text to highlight any references to code (function names, variable names, etc.) i.e. denoted with backticks variable vs variable.
• Do not leave fields blank. If the Project:… and/or Spearbit:… fields are empty or there is nothing significant to add, simply write the issue status for both fields.

Specific suggestions

Make sure that…

1. There aren't any grammar mistakes. e.g., use the grammarly extension.

2. The format is correct for each section and starts on the same line:

- **Description:** 
- The `AssemblyLib` is using non-full word ...

+ **Description:** The `AssemblyLib` is using non-full word ... 

3. All hyperlinks are handled correctly, else it will break the report generator

- Fixed in https://github.com/ProtocolXYZ/v2/pull/319

+ Fixed in [PR 319](https://github.com/ProtocolXYZ/v2/pull/319).

4. Wrap variable names with backtics ''

- signextend

+ `signextend`

5. Complete the issue if its missing information, never leave it empty and confirm its label status (fixed or acknowledged). Use the protocol team's answers and/or ask them for one

- **ProtocolXYZ:** 
- **Spearbit:**

+ **ProtocolXYZ:** We have addressed the issue in [PR 319](https://github.com/ProtocolXYZ/v2/pull/319)
+ **Spearbit:** Fixed.

OR

+ **ProtocolXYZ:** Acknowledged.
+ **Spearbit:** Acknowledged.

6. Do not use hashtags in the issue body as it breaks markdown -> latex generation

- **Description:** Lorem ipsum .... 
- #### Proof Of Concept...

+ **Description:** Lorem ipsum .... 
+ - Proof Of Concept...

Examples

1: Good

Ex 2: Bad (modified for illustration purposes), terrible and incomplete formatting

Ex 2: Good

Ex 3: Bad, missing protocol team comments

Ex 3: Good