Lesson 3: Docs & Communication

Homepage Content Slides Video


This lesson is under construction. Learn from it at your own risk. If you have any feedback, please fill out our General Feedback Survey.


Where to get help

When in doubt

$ <program> --help
$ <program> -h

Most programs allow you to pass a help flag which will print out basic usage. This is useful as a quick reference for how to use the program.

Man Pages

$ man <program>

Man Pages

$ man man

MAN(1)             Manual pager utils                       MAN(1)

       man - an interface to the on-line reference manuals

       man  [-C  file]  [-d]  [-D]  [--warnings[=warnings]] [-R
       encoding] [-L locale] [-m system[,...]] [-M path] [-S list]
       [-e  extension]  [-i|-I] [...]

       man is the system's manual pager.  Each page argument given
       to man  is normally  the name of a program, utility or
       function.  The manual page [...]

Anatomy of a Man Page

Most Man Pages include:
  • Name
  • Flags
  • Description
  • Basic Usage
  • Authors
If you're lucky they will also include:
  • A Good description
  • Advanced Usage.
  • Examples
  • History
  • See Also

Sections of Man

man pages are also organized by section. To read man page for a program/library in a specific section type man #  <program or library> where # is the section number.

For instance:

$ man 2 open # Displays the kernel documentation for open (section 2)
$ man open   # Displays the documentation for openvt (section 1)

If there is a collision in man-page naming (like open and open()) man will pick the page which appears in the lowest-value section.

Sections of Man

  1. Executable programs or shell commands
  2. System calls (function provided by the kernel)
  3. Library calls (functions provided from within libraries)
  4. Special files (usually found in /dev)
  5. Files formats and conventions eg /etc/passwd
  6. Games
  7. Miscellaneous (including macro packages and conventions), e.g., man(7), groff(7)
  8. System administration commands (usually only for root)
  9. Kernel routines [Non standard]


Some distros use info instead of man. To learn more about the info command, see Further Reading.

Project Docs

Projects also document themselves beyond the manpage. These can include tutorials, a README, and Q&A. If you need more information about a tool or a specific answer these docs will probably be your best bet.

These docs may also answer any technical or contributing questions. These docs can be updated more frequently than local man pages so should also be referred to for bleeding-edge information.

Where to look:
  • http://docs.some-random-project.io/
  • http://some-random-project.io/docs/
  • http://organization.com/some-random-project/


Communication is very important for DevOps engineers. Whether they are talking to their own team or working either external projects they use.

It's important to be familiar with the chat platforms that these projects use which include:

XKCD 979, Wisdom of the Ancients


Quick Facts:
  • Internet Relay Chat (IRC)
  • Very old (RFC 1459, May 1993)
  • Works on everything (Terminal, GUI, Web-browser, etc)
  • The people you want to listen to are there
  • Oregon State ran one of the first servers ever!
irssi IRC chat window

Exercise: Getting on IRC

To get on IRC, Use irssi or weechat in screen:

# This step is optional, but persistent IRC is cool
$ ssh <username>@<a remote linux server>

# start screen with the name 'irc'
$ screen -S irc

# start your client in the 0th window of the screen session
$ irssi
# or
$ weechat-curses

# exit irc screen with CTRL+a, CTRL+d
# exit ssh session with CTRL+d or 'exit'
# to get back to irc:
$ ssh <username>@<preferred shell host>
$ screen -dr IRC

Other IRC Clients

If you're not interested in using the command line there also an assortment of graphical IRC clients including Hexchat, MIRC, and KiwiIRC. Look those up if you're interested in them.

HexChat screenshot

There are also a variety of mobile clients for each platform that work well enough. You can also use a mobile SSH client and connect to your server in a pitch.

Unfortunately IRC isn't very mobile friendly.

Connecting and Setup

In the IRC client run these commands (irssi):

/connect irc.freenode.net
/nick <myawesomenickname>
/msg nickserv register <password> <email>
/nick <myawesomenickname>
/msg nickserv identify <password>
/join #devopsbootcamp

For weechat, do the following:

/server add freenode irc.freenode.net
/connect freenode
/nick <myawesomenickname>
/msg nickserv register <password> <email>
/nick <myawesomenickname>
/msg nickserv identify <password>
/join #devopsbootcamp

Commands and Tips

Command Description
/list Reports all the channels on a server.
/topic Reports current channel topic.
/names Reports nicks of users in channel.
/join <channel> Join a new channel.
/whois <nick> Learn about a person.
/msg Directly message an individual.
/help <command> Provides help for commands

Commands and Tips

IRC Jargon

Term Description
channel Chat rooms with with '#' prefixed in front of their names
ping/pong 'I would like to tell you something.' / 'I'm here, tell it to me.'
tail ~
hat '@' Denotes admin status in a channel.
nick Your name.
netsplit When the IRC servers lose connection with each other.
kick/ban/k-line Force someone off the channel or server, typically for abuse


Modern messaging platform which featureful desktop and mobile clients

Slack screenshot


Asking for Help

It's okay to ask for help. Here are some things to keep in mind:

  1. Ask yourself what should be happening?
  2. Ask yourself what is actually happening?
  3. Google the problem(s).
  4. Skim the manuals of each component.
  5. Identify a friend, mentor, or IRC/Slack channel who could help.
  6. When they're not busy, give them a quick synopsis of points 1 and 2, mentioning what possibilities you've ruled out by doing steps 3 and 4.

Contributions = expertise + time

Further Reading

Next: Lesson 4: Shell Navigation