Organize documents by topic rather than type, this makes it easier to find the documentation.Visit Plain English for tips on how to write documentation that is easy to understand.Be clear and concise, stick to the goal of the document.Use inclusive language, and avoid jargon and uncommon words.Save your guidelines together with your documentation, so they are easy to refer back to. The following are some examples of writing style guidelines.Īgree in your team which guidelines you should apply to your project documentation. Is the documentation technically, and ethically correct?.Is the documentation up to date with the code?.Is there a single source of truth or is content repeated in more than one document?.Is the document easy to read and understand and does it follow good writing guidelines?.In addition to the Code Review Checklist you should also look for these documentation specific code review items Markdown-link-check : runs-on : ubuntu-latest steps : - uses : - uses : information about markdown-link-check action options can be found at markdown-link-check home page Code Review Checklist The VS Code extension Prettier also catches all markdownlint errors. It's available as a ruby gem, an npm package, a Node.js CLI and a VS Code extension. Markdownlint-cli is an easy-to-use CLI based on Markdownlint. Markdownlint is a linter for markdown that verifies Markdown syntax, and also enforces rules that make the text more readable. The following are a list of linters that could be used in this setup. Linters are often used to help developers properly create documents by both verifying proper Markdown syntax, grammar and proper English language.Ī good setup includes a markdown linter used during editing and PR build verification, and a grammar linter used while editing the document. It is important to respect this formatting, otherwise some interpreters which are strict won't properly display the document. Markdown has specific way of being formatted. You can find more information and full documentation here. When you create a Markdown-formatted file, you add Markdown syntax to the text to indicate which words and phrases should look different. In an application like Microsoft Word, you click buttons to format words and phrases, and the changes are visible immediately. Using Markdown is different from using a WYSIWYG editor. Created by John Gruber in 2004, Markdown is now one of the world’s most popular markup languages. Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents. CSE developers treat documentation like other source code and follow the same rules and checklists when reviewing documentation as code.ĭocumentation should both use good Markdown syntax to ensure it's properly parsed, and follow good writing style guidelines to ensure the document is easy to read and understand.
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |