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 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.
This post was sourced from https://writers.stackexchange.com/q/6078. It is licensed under CC BY-SA 3.0.
3 answers
You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.
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 comment threads
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
This post was sourced from https://writers.stackexchange.com/a/18519. It is licensed under CC BY-SA 3.0.
0 comment threads
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 ;)
This post was sourced from https://writers.stackexchange.com/a/6086. It is licensed under CC BY-SA 3.0.
0 comment threads
0 comment threads