What we’d like to do here at the end, based on your responses in “Where do we go from here?” is to take some small subset of what you’ve thought about and worked on this semester and refactor it to be publishable. In essence, I think it makes sense to produce a portfolio of 3 pieces and actually get them online, as well as a sort of post-mortem about what you chose, why, and the road to getting it up. There are a few things to consider along the way.
TL;DR:
In the end, you will make a portfolio on your blog, and share with us the URL. You will want at least 5 things in your portfolio:
- A landing page. This should introduce the concept, yourself maybe, and direct the reader to your portfolio pieces.
- Your 3 portfolio pieces. Each of these can be a math problem, a more general topic, or an essay. Exposition is fine, you don’t need an argument about how the world should work, but you do want some details as well as to help the reader understand why you are putting those details to them. More discussion of what to choose and accomplish below.
- A post-mortem. Connect the pieces to one another, discussing your process, etc. To some extent, it is a toss-up what to include here and on the landing page. It is up to you. Have it make sense to the reader.
Technical details
Writing math on the web requires a few separate moving parts to all get along together well. Getting there will require you to be able to assemble and work with
- Latex code. For typesetting math there is no peer. You will need to be able to encode math things, like $\int_0^{\infty} e^{x^2} dx$. As we discussed previously, using just Latex is a fool’s mission. Not only is there a lot of worthless overhead, and confounding language for creating documents and their parts, but what you end up with is more at home on a piece of paper than the web. Instead, we will make Latex useful by taking advantage of
- Mathjax. This is a javascript library that recognizes mathematics typeset in Latex and renders it using its own version of Latex. Many blogging platforms can be rigged, sometimes in multiple ways, to call Mathjax. Earlier this semester, we all set up blogs, configured them to use Mathjax, and tested this functionality with a sample equation, $e^{\pi i}+1=0$.
- Blogging engine and writing environment. You need a place to write and a way to get that writing turned into HTML and displayed at a url. Blogging platforms work well for this. They allow you a place for your work to go, a way to style and organize that work, and even let you host media in addition to your words.
What’s in a Portfolio?
How you organize all of this is up to you. Your 3 pieces can each be “posts” meaning that they come up in the usual reverse chronological order for readers, or they can be “pages” on a website, organized through a menu most likely. Our course homepage is organized as a set of “pages”. My local games lab ABQ blog has blog posts front and center with some “project pages” accessible via the sidebar on the right. This student project website, Celestina Martinez’ Seesign, uses WordPress, a blogging engine, but is laid out as a website of hierarchically navigable pages. It is a good example for you in terms of the amount and type of content represented. Her project was deeper, but the website played the same role. Only, not math.
Like all portfolios, find a logic that holds this all 3 pieces together, a story that they, in concert, tell about you, math, this course. Use the landing page and post-mortem to make that explicit, like an artist’s statement. Consider an audience other than me and how what you wrote is for them. Does this material have an ultimate destiny, a place it belongs other than on your blog? Is it what Wikipedia should look like? Could it work on arbital? Who else might benefit from this and where would they expect or hope to find this? Where would you like to see this work published if you could continue it?
Writing and Publishing
In the end, you turn this in by sharing a url. Although there are a number of ways to proceed, my recommendation is to write simple text files that you can take and share anywhere. Also that you might be able to use to get help along the way. To do this you need, in addition to Latex code,
Markdown. This simple text formatting was designed to make it possible for normal people to write text in a sensible way that could be automatically converted into HTML for use on the web. Markdown is used widely on the web, and is starting to replace the quirky WYSIWYG text environments on forums and blogging platforms. Besides being cool in a geeky sort of way, Markdown promises to make your writing
- Equally readable by humans and computers
- Portable from one place to another via simple copy-paste techniques
Text files. When you write in Markdown, you typically are creating a text file. There is no special format to the document. It is easy to copy and paste this anywhere. Any places that know how to read and display Markdown will accept this copied text and produce nice webpages. Some writing software recognizes Markdown and works as a good tool to write in. Here, you can copy the Markdown and paste as HTML. This way you can put your work pretty much anywhere with little revision. Unfortunately, the places you are most likely used to writing in, Word, Google Docs, do not think in terms of Markdown or do anything special to help you write it. It is still possible to compose Markdown there, but the tool isn’t really helping you. Slack originally used Markdown for its posts but diverged last year.
I wrote this page in Markdown, using a bit of Latex, and posted it to a new page on our website via command-c. I also did this for the rest of the content here, like Problem Set 3. I’ve found that Markdown is a really nice way to write. If your blogging engine supports Markdown and Mathjax, I would highly recommend finding a writing environment that recognizes both and composing your text that way.
Even if Google Drive and Slack don’t understand Markdown, they both still support collaboration on text. You can create and share Markdown documents there to work on them together. Slack does recognize Markdown in its “posts”. I pasted mine here to create this one. Unfortunately, it converts it into its own internal format, so you can’t get Markdown back out.
I don’t imagine you’re crazy to try something totally new, but SageMathCloud does work like Google Docs for Markdown (or Python, C, Sage code, etc.). You can create projects and files there and share them with any other collaborators.
One helpful hint. If you need curly braces in math, {, the latex code is \{ and \}. If you want to describe sets, you need them a lot. But somehow Markdown strips the initial slash and won’t typeset these symbols. But you can trick it into doing so by typing an extra slash: \\{. If you look at the source for this document, you’ll see a lot more slashes.
Style Guide
One of my great hopes is to take your work, combine it with that of others, and put it elsewhere. Things will be portable if among us we can keep a few conventions clear. These go, even outside of Markdown.
- H2 – the 2nd level heading is the one to use for major sections in your documents.
- H3 and so on should be used to provide your document with finer structure, not bold and italics.
- Titles of major works, like the names of books, should be italicized. No quotes or underlines.
- Link text should normally not be a linked version of the actual url. Instead apply a link to a part of your writing.
- Bold text can be used for semi-headings, vocabulary words, and a few other things. Use it sparingly.
- Citing Sources should be done in a hybrid APA/web fashion. Cite sources inline via hyperlink and (Author, Year). A references section should be at the end of each piece or a separate page.
The Perfect Portfolio Pieces
In the end, you get to decide what to put in your portfolio and what it represents about your interests and abilities as you developed them this semester. See each as a chance to have done some thinking towards how to make others smarter. We have spoken at great length, when studying various problems, about the great effect simple choices of presentation can have on the readability of an explanation. From the choice of symbols to the location and style of diagrams, the order of argument, and what you assume about your reader, there are so many things besides the correctness of the steps. Each piece should not only be a chance to say something but also a set of choices about how to say it.
I’m writing this guide with the assumption that you will be writing pieces for your portfolio, but if you wish to avail yourself of other media, by all means go for it. We have come across plenty of videos this semester, and while radio presents some difficulty for math, I think it could be a worthy challenge.
Look back at our readings for different kinds of examples for what could be written about and what the intended effect on the reader might be. Martinez has very different goals in telling mathematical history than Stillwell, even though both are trying to make us smarter. One thing I’d like to see you borrow from both of them is a care for the details. Stillwell’s book is different from most other non-professional math writing in that he digs into the actual problems, equations, etc. He may not always fulfill his promise, like with the Arc Length Problem, but he discusses the importance of infinitesimals in view of the things themselves, not in a generic philosophical way. And Martinez actually goes the the trouble of making a table of all the sometimes only slightly different things historical writers have said about Pythagoras.
Dissatisfaction is the mother of all invention. As a final suggestion for what to write about, think about something we’ve seen or done that needs fixed. Henry Petroski, who has written extensively about some of the most important and mundane inventions, also wrote that being unhappy with the way something currently works, not necessity, is the prime mover when it comes to innovation. Kira Ferguson, a media critic, also notes that almost all cultural production is derivative, taken from something else. Don’t make this too hard on yourself. Find something that needs to be better and rip it off. Steal someone else’s way of improving and apply it here. Be honest about where your inspiration derives, cite your sources, and proceed to make their work yours. Along the way, you’ll introduce something that will make it yours, even if maybe just by screwing something up.
