H2 Sections and Related DescriptionsĮvery header must include at least one sentence under it that describes the context or purpose of that section of the tutorial. When you link to another Semaphore tutorial as a prerequisite, make sure that in preparing your new tutorial, you follow all the commands from that other tutorial yourself. Follow the steps from this tutorial to set up RSpec. Link to a source code repository that the reader should clone.Link to a tutorial about installing prerequisite software, such as Grunt or a sample application.Then, include all of the required items, software, and configurations as separate list items that the reader can use as a checklist.Ĭommon prerequisite bullet points include: Introduce your prerequisites with a sentence or several paragraphs, as needed. What the reader will have accomplished or learned at the end of the tutorial.Methods to be applied and all tools involved.Typically, the introduction should cover: The first section of every tutorial should have a paragraph or two describing the goals, methods, tools and results of the tutorial. When in doubt, use to do the capitalization for you. For example: Rules for Capitalizing the Words in a Title.Īrticles (a, an, the), coordinating conjunctions (and, but, or, for, nor), and prepositions, regardless of length, are lowercased unless they are the first or last word of the title. CapitalizationĪll headers in the tutorial should be written in title case, as described by the Chicago Manual of Style:Ĭapitalize the first and last words of the title and all nouns, pronouns, adjectives, verbs, adverbs, and subordinating conjunctions (if, because, as, that, and so on). When writing any title, prefer Markdown’s “hash marks followed by a space” ( # ) over the underlining syntax.ĭo not use special formatting, such as links or code blocks, in headers. In other cases, try to formulate the title using the gerund (- ing words) and a phrase that summarizes what you are teaching the reader to do. Getting Started with Node.js and Jasmine. ![]() For example, How to Deploy Sinatra Applications with Capistrano.įor introductory tutorials, the title should begin with Getting Started with, e.g. The typical title should follow the format of How to do Task with Tool and AnotherTool. The tutorial should begin with a title using an H1 header, and it should be the first line of your file.įor procedural tutorials, the title should begin with How to. This section explains how to use headers in your tutorial. ![]() The only exception is when a line includes a link with a long URL. File FormattingĮach source line of the tutorial should be limited to 80 characters or less. While this article lists some examples of Markdown applied to writing a tutorial, for a more comprehensive Markdown guide refer to Daring Fireball. Semaphore tutorials should be formatted in the Markdown markup language. If you don’t yet have an approved sample and topic, follow this link to become a Semaphore Community author. ![]() If you have an approved writing sample and topic, you can submit the tutorial as a link to a gist, or as a. Where can I submit the completed tutorial? By following the details in this guide and the companion Style Guide, your tutorial will match all of the Semaphore guidelines. This article explains how to format Semaphore tutorials.
0 Comments
Leave a Reply. |