Community Documentation vs. Technical Documentation.

Shawn Beasley01. Mar 2011 | Miscellaneous

Disclaimer:

The practical examples presented in our technical blog (blog.otrs.com) and now in the expert category in our FAQ blog section serve as a source of ideas and documentation to show what is theoretically possible with OTRS in concrete scenarios or sometimes even for more exotic configurations. All configurations presented here were developed under laboratory conditions as a proof of concept. 

We can only guarantee testing and implementation of these concepts to be error-free and productive if implemented in a workshop with one of our OTRS consultants. Without this, the responsibility lies with the customer himself. Please note that configurations from older OTRS versions may not work in the newer ones.

Dear Readers,

A very old, and mostly abandoned view on documentation or better yet product usage is RTFM. That is all good, in my opinion, but what does the F’n manual tell me? If I look at a man page, for example, I would see something like this:

OPTIONS

All options always return true. They always take effect, rather than being processed only when their place in the expression is reached. Therefore, for clarity, it is best to place them at the beginning of the expression.

-daystart
Measure times (for -amin, -atime, -cmin, -ctime, -mmin, and -mtime) from the beginning of today rather than from 24 hours ago.
-depth
Process each directory's contents before the directory itself.
-follow
Dereference symbolic links. Implies -noleaf.
-help, --help
Print a summary of the command-line usage of find and exit.
-maxdepth levels
Descend at most levels (a non-negative integer) levels of directories below the command line arguments. `-maxdepth 0' means only apply the tests and actions to the command line arguments.
-mindepth levels
Do not apply any tests or actions at levels less than levels (a non-negative integer). `-mindepth 1' means process all files except the command line arguments.
-mount
Don't descend directories on other filesystems. An alternate name for -xdev, for compatibility with some other versions of find.
-noleaf
Do not optimize by assuming that directories contain 2 fewer subdirectories than their hard link count. This option is needed when searching filesystems that do not follow the Unix directory-link convention, such as CD-ROM or MS-DOS filesystems or AFS volume mount points. Each directory on a normal Unix filesystem has at least 2 hard links: its name and its `.' entry. Additionally, its subdirectories (if any) each have a `..' entry linked to that directory. When find is examining a directory, after it has statted 2 fewer subdirectories than the directory's link count, it knows that the rest of the entries in the directory are non-directories (`leaf' files in the directory tree). If only the files' names need to be examined, there is no need to stat them; this gives a significant increase in search speed.
-version, --version
Print the find version number and exit.
-xdev
Don't descend directories on other filesystems.

Wow….. that can be helpful, right?

That is currently hard to say! I think there is a great need for technical documentation, and it needs to be written by tekkies. However, can tekkies write quality useful documentation for today’s administrators and users? Or, is it better to have users writing for users. Looking into the situation, the OTRS community is probing other possibilites for users to write good documentation for users.

There are some burning questions:

  1. Which platform to use?
  2. Will people commit?
  3. What quality can be expected?

Challenges:

  1. Wikis are in general good, but have many technical draw backs, especially in the review process and internationalization.
  2. Users are willing to commit, when it is easy and understandable.
  3. Mileage may vary on quality, therefore it is good to have a standard of editing and an authoring team in the community to ensure a rouge does not break the entire world.

Technical Documentation is much harder to write, and needs to be done by those who are knee deep in the code and current feature set.

Community Documentation needs to be by the users who are plugging away at the software every day and truly know how to reduce tech chatter down to the core basics.

Therefore, I am currently testing Drupal Books Module for community documentation.

Benefits:

Authoring workflow

Translation workflow

Rolls for permissions

Content linking with internal/external resources

Commenting possible in pages

Personal Book Creation

and the list goes on.

Here is what an editor would see (the user just would not see the links above the title)

Book Module Page View

As work progresses, we will see if this beta service is accepted an used.  There is no current release planned for this community documentation, as it is still in the early planning phase. Please keep an eye on the news at otrs.org for updates.

Your Community Manager

Shawn Beasley

Your email address will not be published. Required fields are marked *