Talk:Open writing projects/Scientific Programming with Python and Subversion/Outline

From OpenWetWare
Jump to navigationJump to search

Comments from Lorrie:

I would also recommend you put chapters in Part I since it's weird to find chapter 1 in Part II. You'd keep the part title and have one long chapter with 3 example boxes sprinkled throughout (as I've indicated in the outline), or you'd break the text into multiple smaller chapters. If you did the latter you'd have an introduction and then 3 short chapters each illustrating one example. Does either sound appealing?

Lorrie cracks the editorial whip...

  • In general, try to be consistent. Choose a style and stick with it. For example, headings should all follow the same style: First word capped and all other words lower case, or all words capped. (O'Reilly's style is to have all major words in the the heading capped.)
  • Avoid passive voice. This is a tough one for scientists, all of whom seem to think that using pronouns is prohibited. ;-) Instead of saying "The data suggested that our experiment failed" say "According to the data, our experiment failed."