Skip to content

Latest commit

 

History

History
46 lines (31 loc) · 1.89 KB

patterns.md

File metadata and controls

46 lines (31 loc) · 1.89 KB

Patterns Common in Exemplary Docs

Context & Introduction

Frequent context-setting, including brief definitions of potentially unfamiliar terms and introductory statements about the shared problems the project is intended to solve and how it solves them.

Introductory context-setting in Django https://docs.djangoproject.com/en/1.10/intro/overview/

Introductory context-setting in Browserify https://github.com/substack/browserify-handbook

Inline context-setting in Django https://docs.djangoproject.com/en/1.10/intro/tutorial01/#creating-the-polls-app

Audience-branching context-setting in jQuery https://learn.jquery.com/

Examples Galore

Plentiful examples and tutorials with credible real-world goals.

Getting to the examples right away for PHP http://php.net/manual/en/intro-whatis.php

Django's "quick example" format https://docs.djangoproject.com/en/1.10/topics/db/models/

Django tutorial https://docs.djangoproject.com/en/1.10/intro/tutorial01/

Full List of patterns

  • Completeness balanced with concision
  • Optional depth, including rationale, links to source, and asymmetically deep dives on complex topics*
  • Plentiful examples and tutorials with credible real-world goals*
  • Frequent context-setting, including brief definitions of potentially unfamiliar terms*
  • Statements (usually in intro) about the shared problems the project is intended to solve and how it solves them* (merged up)
  • Clear TOC and information structure, and high-quality search
  • Specific, unintimidating invitations to participation
  • Ordered step-lists and prerequisite/environment checklists*
  • Unobtrusively encouraging tone
  • Designed for both easy topic-finding and more in-depth reading

(* good candidates for building out in more detail)