sn-00000-sys-notes-introduction March 27, 2010
Introduction to System Notes
Raymie Stata (Yahoo!, Inc.)

Sequentially-numbered series of technical documents are a commonly-found artifact in the world of systems research. Well known examples include:

Over the years, more and more discoveries in systems building occur outside of institutions with a tech-report series. Practitioners are using alternative forums to report their discoveries, for example, tech talks on You Tube, Power Points on Scribd, inidivually posted papers, online technical magazines, and, of course, hundreds of technical blogs.

While each of these new forums has its value, none of them provides exactly the value of a good technical note:

In short, there's a gap in the publishing options for today's systems builders: a place to publish "technical notes."

The goal of www.sysnotes.org is to fill this gap. Sysnotes is a place to publish technical notes about scalable, computer systems, and especially scalable Internet services. In keeping with the philosophy of Agile Development, my goal is to let sysnotes evolve according to the needs of its customers, which are the authors of sysnotes. In this regard, I'm inspired mostly by the example of Dijkstra. Quoting Wikipedia: "Looking closely at himself, [Dijkstra] realized that if he wrote about things they would appreciate at the MC in Amsterdam his colleagues in Eindhoven would not understand; if he wrote about things they would like in Eindhoven, his former colleagues in Amsterdam would look down on him. He then decided to write only for himself, and in this way the EWDs were born."

Few of us will generate over 1,000 notes the way Dijkstra did. For those of us who have even a small number of notes in us, sysnotes.org will be a forum for publishing them to our colleagues. Sysnotes.org will offer the following benefits for authors:

For system-building professionals who don't ordinarily share their thoughts with a wider audience, sysnotes.org will offer them a publication option that they may find convenient. For system-building bloggers, sysnotes.org is a complementary medium: they can publish longer trains of thought in a note, then post a summary of and link to that note in their blog.

A mentioned above, the site will maintain a threshold for quality. The exact criterion will evolve over time. While quality of writing will be a consideration, novelty will be the primary criteria. This means either novel ideas, or novel expressions of ideas. This last is important: an existing idea expressed in a new way, or in a new context, leads to deeper understanding and appreciation.

Regarding format, documents must be formatted using HTML. Documents will be given a number and an SEO title. The SEO title is a sequence of keywords separated by hyphens that will be used in the URL of the document (e.g., the SEO title of this document is "sys-notes-introduction"). Diagrams and other images are encouraged: documents should link to such assets using a relative path that assumes the assets and the document will be stored in the same directory.

Documents should follow the minor formatting conventions established by this first system note. There is a style sheet that establishes division and spans for the header, title, and author(s). If you post an announcement to your blog, please include the permalink to the entry at the bottom of the note. Finally, always include a Creative Commons license as the very last item in the note.

Announcement and comments: Master The Fundamentals


Creative Commons License This work is licensed under a Creative Commons Attribution-No Derivative Works 3.0 United States License.