Skip to content

Latest commit

 

History

History
56 lines (44 loc) · 6.75 KB

WR1-Tutorial-Blog.md

File metadata and controls

56 lines (44 loc) · 6.75 KB
title
Writing (210A): Tutorial Blog

Objective

The purpose of this assignment is to give you practice writing technical documentation for others to use. Throughout the semester you have inevitably read many online tutorials and “how-to” posts that introduce you to unfamiliar technologies. Now is your chance to create one of your own. To benefit others, I strongly encourage you to post your tutorial in the form of a public blog (e.g., on Blogger, a personal website…), though it is up to you if you want to share it with the world or not. Either way, a file with the content should be uploaded to LearningSuite by the due date.

Procedures

Step 1: Choose one topic from the list below. Your tutorial will comprehensively cover the topic.

  • Positioning data in rows and columns using CSS. (There are multiple methods, explain just one.)
  • Storing, accessing, and displaying JSON data in local storage.
  • Setting up sessions in PHP.
  • Storing data in cookies, managing their lifetime and scope.
  • Using a CSS Framework (like Bootstrap, Tailwind, Foundation, etc.) and customizing it to your needs.
  • Another topic approved by your instructor that is similar in scope.

Step 2: Write a blog post of approximately 1,500 words (e.g., about 3-4 single-spaced pages with a few code snippets and screenshots). It must be your own work. If you quote other tutorials or materials, they must be cited appropriately. The blog post should include the following sections:

  • Introduction: Introduces the technologies that will be used and some high-level background on why they are used and what they are designed to do.
  • Tutorial: The actual steps that those completing the tutorial will need to take, along with explanatory text (why you are recommending what you’re recommending), commented code snippets, and/or screenshots to walk them through the process. It should not assume any knowledge of the topic at hand, but can assume a basic understanding of “clients” and “servers”. All code should be carefully explained in readable English to people with only a basic understanding of programming. Explanations of why you are doing things are essential, not just the steps to perform them. Discuss any unexpected or potential implications of the approach taken and any tips and/or warnings.
  • Additional Resources: An annotated list of 4-7 high-quality resources (e.g., websites, books, videos, documentation…) related to the topic at hand should be provided with hyperlinks and brief annotations explaining what they are and why they might be useful (e.g., “http://madeupCGIwebsite.html: This CGI website is an excellent resource for understanding the history of CGI and best practices for implementing it. All examples use Perl. It is at the level of an intermediate programmer. The section describing... is particularly good, while the section describing... is a bit outdated.”)

Submitting Your Blog

You must submit your blog post in LearningSuite in one of the following formats:

  • .pdf (Save to this if you write it in Microsoft Word or Apple Pages)
  • URL Link to your post on a cloud drive site such as Google Docs, OneDrive, Box.Com, iCloud, etc. If you use this option, be sure to set read permissions to "Everyone with this link."
  • URL Link to your live post on a public site. (See Extra Credit below.)

Note: You may write the post in your favorite word processor like Microsoft Word, Apple Pages, or some such. But save to .pdf format before submitting. Pretty much any word processor can do that. In this class, we emphasize using web-compatible formats.

Grading Rubric

Your assignment will be graded based on the following for a total of 50 points possible:

  • Comprehensiveness and accuracy of content (30 points)
    • Introduction (5 points)
    • Tutorial Content (20 points)
    • Additional Resources (5 points)
  • Clarity & accuracy of technical writing (10 points)
    • avoid vague terms like “it” when stating what “it” is would be clearer
    • Make sure to introduce terminology that may be new.
    • make sure your statements are not ambiguous (e.g., “the JavaScript AJAX call, which is initiated by the browser, passes the XYZ array variable via the GET method to the Apache server” a is better than the vague and ambiguous “the client then sends the data to the server”)
    • Make sure your statements are accurate (e.g., “Store the JSON object in local storage” is not accurate, since only strings can be stored. Instead say “Store the ‘stringified’ JSON object in local storage”).
    • Use appropriate headers for subsections so people can quickly find where they want to go if they are only scanning the tutorial for certain information.
  • Style, grammar, and spelling (10 points)
    • Avoid grammatical and spelling errors (e.g., changing tenses within a section; plural/singular agreement problems such as “the [singular] user did this, and then [the plural] they did that”)
    • Code snippets should be in a different font than the explanatory text. Use a monospace font (e.g., Courier New) that clearly differentiates between otherwise hard-to distinguish letters: l, 1, I, (l, 1, I).
    • All figures/screenshots should be labeled with appropriate titles (e.g., Figure 1: JSP “Hello World” code). Not all code fragments need to be labeled unless you want to refer to them more than once.
    • You are writing for your peers. Unlike the lab write-ups, this does not need to be a formal writing style. You can use first-person pronouns (“I like to…, because it…”) and refer to the reader as “you” (e.g., “you’ll want to make sure that you don’t…”). A bit of humor is even appropriate if it doesn’t distract, though it’s not required – I’d hate to be responsible for a bad joke just to get a good grade. 😬
    • Use appropriate formatting. Assume it’s a blog post style, so do things that are appropriate for that style such as embedding hyperlinks into sentences, not pasting in long, full URLs.
    • When writing for the web you’ll want to use hyperlinks to point to topics or resources that may help explain things in more detail. For example, the first time you use a technical term (e.g., “aspx” “tasksel”), you can link to a site that defines it and provides details about it.
  • Extra credit (10 points)
    • Publish your blog post on a public website. This could be an article on LinkedIn, a comprehensive answer on StackOverflow, a GitHub Gist, a post on your own blog, or a helpful article on numerous other blogging or content management systems.