Technical Writing 1: Annotated Bibliography

In this class we will only scratch the surface of a few web technologies. This assignment looks to:

  • Have you practice learning a new technology on your own.
  • Learn to document that knowledge, so you can contribute that knowledge to your team and even larger computing community.

For this assignment, we’ll create an annotated bibliography. Rather than pick up the first tech documentation that we can find, we want to survey what’s out there and pull from the best choices.

Step 1: Pick a Topic

Step 2: Set Up GitHub

See class video for a step-through on how to do this.

Step 3: Find Resources

Find five sources. At least one from these:

  • On-line
  • A book. If the library doesn’t have a book you need, let me know. We’ve got library budget money we need to spend.
  • On-line database like EBSCO https://simpson.edu/internal/dunn-library/students/databases-z (There are a lot of way-cool sets of articles, like stuff from ACM, IEEE, but are pay-for.)
  • One video from a conference.

If you can’t find a source from all four, let me know.

Step 4: Write the Annotated Bibliography

Your bibliography should look like:

The Web application security topic from Wikipedia [1] would be a good place to start. This covers [summary]. I could pull from this [specific info].

[1]Wikipedia contributors. (2021, January 21). “Web application security”. In Wikipedia, The Free Encyclopedia. Retrieved 17:32, January 31, 2021, from https://en.wikipedia.org/w/index.php?title=Web_application_security&oldid=1001721387

The code would look like:

The Web application security topic from Wikipedia [#f1]_ would be a good place
to start. This covers [summary]. I could pull from this [specific info].

.. [#f1] Wikipedia contributors. (2021, January 21).
   "`Web application security <https://en.wikipedia.org/wiki/Web_application_security>`_".
   In Wikipedia, The Free Encyclopedia. Retrieved 17:32, January 31, 2021,
   from https://en.wikipedia.org/w/index.php?title=Web_application_security&oldid=1001721387

Use APA style.

Cite the original source. If you cite something like Google, Amazon, Wikipedia, you might have issues. These companies rarely create content. You might find the image or information with their tools, but then use some detective work to find the original source. For example, above I used Wikipedia. I might want to site that 37% of vulnerabilities are cross-site-scripting. That info did not come from Wikipedia, but security vendor Cenzic, in a March 2012 article.

You might find yourself wanting to list a website as a source. Remember that the source isn’t “wsj.com”, the source is “Wall Street Journal.” Sometimes the “about” page has this information. If you can’t figure out who the publisher is, it probably isn’t a good source.

If using an auto-citation formatter, beware of “n.p.” for no publisher and “n.d.” for no date. If I see a publisher immediately followed by “n.p.”, it indicates that not much thought was put into the citation. If you can’t figure out the entire date, at least try to narrow it down to the month or year.

I don’t want to see the text of a URL, but please do use a link to reference the original source as shown in the example above.

Remember: A list of URLs is never ok for a bibliography.

Step 5: Check Restructured Text

Make sure your project builds without warnings.

Make sure you don’t type beyond 80 characters or so per line. While this isn’t a hard-and-fast rule, it is a guideline. You can set up visible guidelines in File…settings…editor…code style…visual guides.

Check spelling and grammar. PyCharm can be configured to spell-check so pay attention to that.

Make sure your landing page and table of contents look correct.

Step 6: Turn In

Turn in a link to your GitHub, and a link to your Read-The-Docs page.