ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/expansion-packs/bmad-technical-writing/checklists/oreilly-format-checklist.md

2.9 KiB
Raw Blame History

O'Reilly Format Checklist

Use this checklist to ensure manuscripts meet O'Reilly Media formatting and style requirements.

File Format

  • AsciiDoc or DocBook format (check your editor guidelines)
  • UTF-8 encoding used
  • Files named according to O'Reilly conventions
  • Version control used (Git typically)
  • Atlas platform requirements met (if using O'Reilly Atlas)

Style Guide

  • Chicago Manual of Style (16th or 17th edition) followed
  • O'Reilly Word List consulted for technical terms
  • Consistent capitalization and spelling
  • Proper formatting for technical terms
  • Style sheet provided by editor followed

Structure and Markup

  • Proper heading hierarchy (chapter, sect1, sect2, sect3)
  • Headings use title case
  • Cross-references formatted correctly
  • Inline markup used appropriately (emphasis, strong, code)
  • Lists formatted properly (itemized, ordered, variable)

Code Examples

  • Pygments language tags specified for syntax highlighting
  • Code blocks use appropriate callouts
  • Tabs converted to spaces (typically 4 spaces)
  • Line length appropriate (typically 80 chars for print)
  • Code listings numbered if referenced
  • Callouts explained in text

Typography

  • Curly quotes used (not straight quotes)
  • Em dashes formatted correctly (—)
  • Ellipsis character used (…) not three periods
  • Non-breaking spaces used where appropriate
  • Special characters encoded correctly

Cross-References

  • Internal cross-references use correct syntax
  • Chapter and section references formatted properly
  • Figure and table references included
  • Appendix references correct
  • URL handling follows guidelines

Figures and Tables

  • All figures submitted in required format (EPS, PDF, or PNG)
  • Figure captions written in complete sentences
  • Tables formatted using appropriate markup
  • Table captions provided
  • All visual elements referenced in text

Technical Accuracy

  • Code tested and working
  • Version numbers specified
  • URLs verified
  • Technical terms used correctly
  • Examples represent best practices

Editorial Elements

  • Sidebars formatted correctly (notes, tips, warnings)
  • Footnotes or endnotes formatted properly
  • Glossary terms marked (if applicable)
  • Index terms marked
  • Bibliography formatted correctly

Front and Back Matter

  • Preface includes target audience and prerequisites
  • Conventions section explains code formatting
  • Acknowledgments included
  • Colophon requirements met (if required)
  • Copyright and licensing clear

Submission Requirements

  • All files in agreed format
  • Complete manuscript package
  • Permissions for third-party content obtained
  • Code repository organized and accessible
  • Author questionnaire completed
  • Production editor requirements met