RSK Articles Guide

# RSK Articles Guide ## Rules #### Mention prerequisite knowledge needed for following through with the tutorial Quickly mention the intended audience for your tutorial, the prior knowledge they need before they can follow through with your tutorial, e.g In this tutorial we use the Command line to install XCode, you can include links to available resources. #### Acronym or abbreviation Introduce acronyms and their full meaning before using the acronym in the entire tutorial, e.g, How to use Truffle and OpenZeppellin (OZ) to create Smart Contracts. You can then use OZ throughout the entire tutorial but endeavor not to switch between the both - OpenZeppelin and OZ, just stick to one of them. You may also hot-link the acronyms where necessary. #### Be Detailed Be specific and detailed. Try as much as possible to avoid assuming anything for the reader. Breakdown all the steps no matter how minute, since everyone might not be using the same operating system or might not start from the beginning of the tutorial. If users ask common questions about a particular step in your tutorial, consider adding in the answer as part of the tutorial, rather than hoping others with the same question navigate to the comment where you answered. For example, **Open up Finder > Under Applications > go to the Utilities folder > locate the terminal and double-click to open it**. #### Follow Your Instructions The point of a tutorial is to walk a reader through something they've never done before. If the tutorial has errors the reader won't have much in the way of resources to help them correct it as they are obviously not experts on the subject; if they were then they wouldn't be reading the tutorial in the first place. If possible triple-check your tutorial before publishing. #### List Version Number List the version number of the software you used in the tutorial, e.g, How to setup your local node with docker 4.2. #### Show Code Samples Try to show code samples in the tutorial or insert a link to where the full code is stored e.g a link to the full code on github. #### Use metadata Presently front matter or metadata at the top of each page’s source file is optional, but we do have a view to make this compulsory in the future. Please ensure that any pages that you update or create have at minimum, the following items: title, tags, description. #### Avoid images of text Do not take a screenshot of your text, for example in a code editor or terminal window, and insert this as an image into the tutorial. If you do so, both the reader and search engines lose the ability to search for code snippets, and you lose a lot of detail. Further to this, it makes for a larger workload, and results in a higher likelihood of error when the tutorial needs to be updated. What to do instead: Use the appropriate markdown code fence syntax to demarcate text for special rendering, such as `windows-command-prompt`. #### Avoid links whose text are “here” or “click here” Do not use something like - To find out more `[click here]`. or similar. Do this instead - Check out [xyz] for more information., or similar. The text of the links should reference the title of the page being linked to, or should describe it in some way. #### Avoid external images Do not use images that are hosted externally, for example [imgur.com](imgur.com). Instead commit them into the repo, and link to that instead. See also: [Avoid images of text](#Avoid-images-of-text). #### Consider that external links will break when moving/ deleting/ replacing pages If you are doing something to an existing webpage such that it will no longer be accessible at the same URL, be aware that there are other websites/ group chats/ social media posts that may already link to the original URL. In general, avoid deleting any pages. If you are replacing one page with another, find a way to keep both. In all cases, set up redirects. The end goal is that if a URL changes, the end user should never see a “HTTP 404 Not Found” error if they click on a link with an old URL. #### Check for broken links In your article, you may reference other web pages, both internal and external. Check that they all work. Use a script to automate this task, if applicable. #### Check for broken images Ensure that all of the images are indeed present. Ensure that images that are not referenced have been removed/ not committed, if applicable. See also: [Avoid images of text](#Avoid-images-of-text), and [Avoid external images](#Avoid-external-images). #### Consult the English FAQ grammar section This contains a list of commonly encountered incorrect phrases, and what they should be instead. See [English FAQs]( https://docs.google.com/spreadsheets/d/18oRGLvxkCuVGt1XwBJRWxHcMlu-5vkQxXuClOCFbUBg/edit#gid=0&range=A1) #### Consult the English FAQ terminology section This contains a list of commonly encountered incorrect terms, and what they should be instead. See the [Terminology Section]( https://docs.google.com/spreadsheets/d/18oRGLvxkCuVGt1XwBJRWxHcMlu-5vkQxXuClOCFbUBg/edit#gid=216662770&range=A1) #### Consult the content structure and URL structure plan When creating (or moving) an article that is within a site full of other articles, when deciding what its new location should be, consider the topic + subtopic, the article type, logical grouping, et cetera. The easiest way to do this is to create planning documents for the content structure and URL structure. If applicable, consult the [URL Planning](https://docs.google.com/spreadsheets/d/1O1kwwysOjmVozF_B0vt-glseUZG2G_FUlgiU4XQ4VBw/edit?usp=sharing) and [Content Structure](https://docs.google.com/document/d/1Svymi62zb3aLN3FBiIJXqq5TpLz3bmGgQKT8KTnSEgU/edit?usp=sharing). ## Technical Writing Courses and Resources [Tech Writing for Software Engineers](https://developers.google.com/tech-writing) ## Approved Style Guides [Google Style Guide](https://developers.google.com/style)