The Minimalist's Guide to Writing for "500 Lines or Less"

Structure

You may know exactly how you want your chapter to be laid out already; if that's the case, go for it (although you may want to run your idea by us first at aosa@aosabook.org.

When first getting started, find somebody and tell them the story of your program before even worrying about an outline. What problem is it solving? What are the important concepts in the solution? This is a first attempt to unearth contradictions in your work, and to identify what you should say instead.

Telling your story out loud is the chapter-writing equivalent of rapid-prototyping. Pay attention to the unexpected ideas or contradictions that pop up, those might be the actual focus of your chapter.

Your goal is to find the "big idea" in your chapter -- a single organizing story or theme that you can build your writing around.

Once you've got that one big idea, feel free to field it with us (see email above) before you even start writing!

Outlining from here should be easier than if you'd started with the outline first :) If you're getting stuck on the layout of the chapter, a sample outline might look like this:

• Introduction to problem you're solving
• How that problem has been changed or simplified for purposes of this discussion
• Introduction to language and/or toolchain you're using, if it's something your average early-career developer may be unfamiliar with
• Exploration of your code submission, with prose interspersed with code blocks.
• Ideas to explore:
  • What the organizational units are (e.g. modules, classes)
  • Why things were modularized the way they were
  • Points of extensibility
  • Tradeoffs: time/space, performance/readability, etc.
  • Patterns or principles used that could be applied elsewhere
• Conclusion:
  • Further extensions that could be made
  • Similar real-world projects to explore

Formatting

• We are going to be using Pandoc Markdown as the markup lingua franca for this book.
• You can use footnotes for citations, and we will deal with making them Look Pretty in the final version.
• Use fenced code blocks for your code excerpts.
• You can install Pandoc if you'd like to check if your Markdown is Pandocable, but this is purely optional.
• If you'd rather submit your chapter in some other format, just let us know and we'll deal with it. We don't want our typesetting choices to slow you down.

Example Chapters

• We will post here and announce on mailing list as these become available.

Other resources

• The Etherpad notes from our June writing tutorial with Greg Wilson lives here: https://etherpad.mozilla.org/500lines