Writing a programming book: how to present directory structures

Question

What is good/preferred way of presenting directory trees in programming books?

My main criteria are following:

1. It should be readable and intuitive
2. It shouldn't take too much page space
3. It shouldn't require too much effort from author to create and update

Examples of situations when presenting directory tree to the reader is required include describing:

• sample programming projects (e.g. "Hello World" project using some technology),
• project layout conventions (like Java EE convention, Maven convention etc.),
• important directories and files of some installed application (e.g. layout of Tomcat directories),

For now, following forms come to my mind:

1. Listing of Unix/linux ls -R invocation on file tree of interest, e.g.

   $ ls  -R /etc/sysconfig/networking
   /etc/sysconfig/networking:
   devices  profiles
   /etc/sysconfig/networking/devices:
   /etc/sysconfig/networking/profiles:
   default
   /etc/sysconfig/networking/profiles/default:
   

2. Manually constructing directory tree "images" from ASCII characters like "|" or "-"

   |-myproj
     |-WEB-INF
       |-classes
       |-libs
   

3. Creating a screenshot of project tree view of some IDE (e.g. Eclipse)
4. Describing file structure textually, e.g:

   Root project directory should contain WEB-INF subdirectory which in turn should contain classes and libs subdirectories

5. Using some advanced modelling tool like Microsoft Visio to generate diagram showing directory structure?

Below are my impressions for the options I already written out:

Option 1: is very terse and is readable and familiar for advanced programmers, but I dare to say not all programmers (especially younger ones) are really familiar with Unix or command-line programming in general.

Option 2: is should be readable for most of readers but doesn't really look professional

Option 3: it will probably look professional but:

• Not everyone must be familiar with given IDE (alhought it shouldn't really matter)
• IDE GUI quickly becomes outdated
• It isn't really easy to update

Option 4: it is OK for the simplest cases. But for more complex it can easily become confusing and verbose. They say that "A picture is worth a thousand words"...

Option 5: such diagrams are likely to take a lot of space and in practice may be less readable than option 1 or 2

So my questions to you are:

• Do you know any more solutions that the ones I stated above? Maybe I'm missing some good one(s)?
• Do you know if any solution is widely adopted in professional programming books? Which one do you meet most often?
• What solution do you personally find best?
• Do you have experience with writing programming books? How did you solved this problem?

PS. I'm not 100% sure if I'm writing on right forum but it seems the best suitable for this question from all of forums I found in stack exchange.

Answer 1

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.

Answer 2

I would go with option 2. However, you do not need to manually build the structure. I instead recommend using a tool such as Tree which should handle the pretty-printing for you as below:

$ tree -d /var
var
|-- backups
|-- cache
|   |-- app-install
|   |-- apt
|   |   `-- archives
|   |       `-- partial
|   |-- apt-xapian-index
|   |   |-- index.1
|   |   `-- index.2
|   |-- cups
|   |   `-- rss
|   |-- debconf
|   |-- dictionaries-common
|   |-- flashplugin-installer
|   |-- fontconfig
|   |-- hald
|   |-- jockey
|   |-- ldconfig [error opening dir]
|   |-- man

The script should be available as a package in your distro. I can confirm that it is in Ubuntu.

I also suggest that you contact your editor to get his/her opinion. The publisher very likely has its own style guidelines for such matters (with layout in mind). If you do go ahead with a text representation, I recommend that you add a sticky somewhere reminding you to check the indentation in the final - whitespace often gets messed up when the book is laid out.

P.S. ... and your editor will prefer a textual representation as well - saves ink ;)

Answer 3

Focus on your main goal:

It should be readable and intuitive

The other two goals make your life easier, but not necessarily the lives of your readers. Your readers come first.

So screenshots of a directory structure would be easy to comprehend. But if you have stress and have to finish the book because of some deadline, what will suffer most? Yes, revising the screenshots. Are they still correct? Do they correspond with the text? Is it easy to miss important things in a hurry? Yes. If they were easy to change, they would serve your readers better.

You see, I fooled you in the beginning, but that had it purpose: focusing.

"Looking professional" is an odd term, much overused, seldom defined. Care about the look later, or in between, but not at the beginning, you can change things.

So, you do not like

|-myproj
  |-WEB-INF
     |-classes
     |-libs

Then make it simpler. What about

-myproj
   -WEB-INF
      -classes
      -libs

Directory structures are hierarchical structures. Show the hierarchy and you are fine. Don't overstress showing some lines pointing from parent to child, just indent. That should be fine.

Answer 4

Try tree -d at the CLI. Does pretty much what you want - automatically and should be easy to copy and paste into a document.

shelelia@halo:~$ tree -d installs
installs
├── bash_library
├── dropbox
│   ├── DEBIAN
│   ├── DropboxServiceMenu-0.16.1
│   │   └── dropbox-scripts
│   └── kde
├── HP
...

It looks better on a terminal than in this post.

Answer 5

Wasabi offers two approaches to it (you can find them both here)

either indented

root/ # entry comments can be inline after a '#'
      # or on their own line, also after a '#'

  readme.md # a child of, 'root/', it's indented
            # under its parent. 

  usage.md  # indented syntax is nice for small projects
            # and short comments.

  src/          # directories MUST be identified with a '/'
    fileOne.txt # files don't need any notation
    fileTwo*    # '*' can identify executables
    fileThree@  # '@' can identify symlinks

or detailed

root/
  this is a comment on 'root'

root/readme.md
  comments are indented under their entry this
  comment is for 'readme.md', a child of 'root/'
  it's specified by the full path

root/usage.md
  the detailed syntax is good for large projects
  and comprehensive commenting

root/src/
  directories MUST be identified with a trailing '/'

root/src/file.txt # some file