: 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

Vote Up Vote Down

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

(0)

Vote Up Vote Down

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.

(0)

Vote Up Vote Down

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 ;)

(0)

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)

Vote Up Vote Down

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.

(0)