Detailed Documentation

Latest response

The difference between RedHat documentation and IBM documentation is you can read the basics in RedHat in two pages, and gleen it out of IBM in 500 pages. But RedHat omits detailed explanations, while IBM provides everything you would ever want to know.

For instance, when I was configuring RHEV last year, there would be a half page section on what a whole chapter should have been written. For instance, when attaching RHEV to EMC, a very common configuration. Why were there general comments without a "how to" white paper, a different link for on board disk, and yet another for other implimentations?

has there ever been efforts to provide detailed information in links within RedHat documentation. To start providing the detailed documentation that the other *ix's provide?

Is there interest with others in doing this.

When I was setting up bonding. It took over a week and lots of time on the phone with RedHat. When I was done. I could have written a detailed paper on how to set up and test Mod1 and Mod4 bonding. Including mentioning the open source tool CDPD (cisco discovery protocal daemon) tool that allows you to see what the cisco router sees...is the port up, is it configured for mod4 bonding? Troubleshooting guide?

Responses

I think our documentation style comes from the fact that we are an open source company. Instead of 500-page manuals, we have shorter manuals, but supplement with special information in different ways. 

Besides manuals, we produce KCS solutions, articles, tech briefs, videos, and reference architectures. You can find information on these content types by searching the Red Hat portal (access.redhat.com).

We're looking for new ways to bring these types of knowledge together. Recently, we have started product pages. If you haven't seen it already, check out our Red Hat Enterprise Virtualization product page:

https://access.redhat.com/products/Red_Hat_Enterprise_Virtualization/

If you look through the Deep Dives heading, you can see that we have organized different kinds of information by where you are in the lifecycle of the product (planning, deploying, maintaining, etc). I'm hoping this will let us get good information to you faster than the production of huge, monolithic manuals will allow. Let us know what you think.

Thanks for your feedback. I've noted your suggestion on documenting how to attach RHEV to EMC and improve bonding documentation (there are documents on bonding, but there is room for improvement). I'm also glad to hear other specific suggestions on documentation gaps that need filling.

Suggestion for Red Hat.

A poorly advertised source of good information already on the Red Hat web site are the archived Red Hat Summit presentation files.  You will find them if you either browse to the Red Hat Summit area of the web site, or use "search", but you will not find the presentation cross-linked or cross-referenced in the mainstream areas of the web site .... like the product documentation section.

Perhaps there should be a way to promote or cross-link useful Summit presentations and even curated informative forum postings into the mainstream product "documentation" areas of the web site.

There is also a wealth of low-level information that is often in the documentation ".txt" files that are stored in the source tree, and sometimes also in the /share/doc tree.  This information is often not posted anywhere in the Red Hat web site.  This forces the customer to download the RPM, and extract the information.  Depending on the package, this documentation may not be in the primary package that gets normally installed, but in some ancillary "developer" or "debug" package.  In some instances, the details of how to properly install and configure the product are only available after you install the product ... this is the classic chicken-and-egg.

For man pages, Red Hat does make most of the man pages available online without installing the package or downloading the RPM. 

I would suggest, a similarly valuable group of documentation are the source tree .txt files, and /share/doc files ... that are often referenced in the man pages.  Making this information available online would be helpful ... especially if it is accurate for the software package version used in the Red Hat bundled collection.

Just some thoughts.

Dave B