Post History

Source: https://writers.stackexchange.com/q/6078
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

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.

Original score: 19