: Re: Writing a programming book: how to present directory structures What is good/preferred way of presenting directory trees in programming books? My main criteria are following: It should be readable

@Turnbaugh521

Vote Up Vote Down

I do something similar to your ASCII implementation, but instead of an ASCII block I use compact bulleted lists (with sub-lists). File/directory names are still styled as they would be in running text. In addition to conveying the structure, this also gives me a handy place to add explanations where needed, which is particularly important when (from the user's point of view) the information is new. For example, my approach would let you explain what WEB-INF is for. (In that bullet: "WEB-INF: explanation." Typography distinguishes name from explanation.)

Screenshots are usually a bad idea in my experience; they have to be edited/updated separately so they might rot (as @Piotr said), and if the document isn't WYSIWIG but, say, HTML, the author of the document might not see the screenshot "inline" while editing. Not seeing the screen shots in your (say) text editor can lead to text-screenshot mismatches. Further, screenshots aren't as visually accessible as text; they don't work with screen readers (unless you also type everything is alt text) and readers can't style the page for font sizes, colors, or contrast. This doesn't mean never use screenshots or other graphics; they're an important part of many documents. It does mean to not use them when they're not necessary. In this case, you have a text alternative that provides the same information, so you should prefer that.

(0)

Login to post a comment!