Tables are easily navigable for sightless users so long as the content is organized in a logical way. In tables, column widths are the same for all rows, which can make them easier to scan visually. Tables are generally suitable only for data: two or more “objects” (rows) that share two or more “values” (columns). In the 18F Handbook, we emphasize the name of the interface label like so: Select or deselect checkboxes and radio buttons.Use clear verbs to tell readers how to interact with interface elements: SomeCl3v3rN4me is the name of our Wi-Fi network. The same rules apply to pieces of text that must be used exactly as presented, such as passwords or Wi-Fi network names: Use straight quotes within code blocks rather than curly (or smart) quotes. getElementById ( " mySelect " ) var value = el. In JavaScript, to get the current value of a select element with an id of mySelect, use this: Use fenced code blocks for multi-line code snippets, and specify the language to enable syntax highlighting on GitHub: “Label” is both a concept and an HTML element but is used here in the former sense and should not be styled as code.ĭo not capitalize code elements, even at the start of a sentence, unless the term is capitalized in the code itself. “Element” is a technical concept and shouldn’t be marked up as code. In the first example, legend is an HTML element and should be styled as code. Use the legend element to offer a label within each form element.Ĭopy and paste mkdir /home/foo/doc/bar & cd $_ into Terminal. Use backticks to style text and code snippets readers may want to copy and paste. Include a short two- or three-sentence summary about the document to help the reader confirm whether they’re in the right place, and improve search engine indexing. (If you’re writing articles for the 18F Handbook or 18F Pages, the table of contents will auto-generate based on your, , and tags or Markdown headings.) Introduction Verbs: Create an account, File a report, Download our data.If your guide or tutorial has several pages, stick to the same naming convention for scannability, such as: Guidelines Titles and headingsīe consistent with how you phrase titles. (This is known as using positive language.) To get started, create an issue in GitHub with details about your request.įocus on what the reader can do rather than what they can’t. Help us understand what kind of help you need by creating an issue in GitHub.Ĭreate an issue with details about your request. Start your sentences with active verbs or clear objectives. Verify the spelling and capitalization as you write. Refer to navigation labels, buttons, and menus as they appear in the app or website. Use short, simple sentences with words people use in everyday conversation. Break instructions or processes down into individual steps. ![]() Basics Do the hard work to make it simple These guidelines will help you write clear, concise instructions, which will provide your reader with the best possible experience. In most of these cases, it’s safe to say the reader is learning something new or troubleshooting. ![]() At 18F, we often write technical documentation, guides, forms, and interface messages.
0 Comments
Leave a Reply. |
Details
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |