What is good/preferred way of presenting directory trees in programming books?
My main criteria are following:
- It should be readable and intuitive
- It shouldn't take too much page space
- 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:
- Listing of Unix/linux
ls -Rinvocation 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:
- Manually constructing directory tree "images" from ASCII characters like "|" or "-"
|-myproj |-WEB-INF |-classes |-libs
- Creating a screenshot of project tree view of some IDE (e.g. Eclipse)
- Describing file structure textually, e.g:
Root project directory should contain WEB-INF subdirectory which in turn should contain classes and libs subdirectories
- Using some advanced modelling tool like Microsoft Visio to generate diagram showing directory structure?
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.