Right size examples?

Nothing illustrates a point as well as a good example. Sometimes even a mediocre example illustrates a point better than several paragraphs of text.

Sample code

Trouble comes when the example is not complete enough to test automatically. One change in naming can make the code silently out of date.

Trouble also arises when the example is so realistic that an untrained eye cannot determine which trees are important in the forest of information.

The example above is too short to compile, but still full of extra information that could distract a reader from the essential points of getting a connection from the factory, binding as Babs Jensen, and finally closing the connection.

How have you solved this problem in your docs?

Advertisements

Leave a comment

Filed under Docs

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s