Bug 1225937
| Summary: | /usr/share/doc/openscap-1.1.1/README update | ||
|---|---|---|---|
| Product: | Red Hat Enterprise Linux 7 | Reporter: | Martin Žember <mzember> |
| Component: | openscap | Assignee: | Šimon Lukašík <slukasik> |
| Status: | CLOSED ERRATA | QA Contact: | Marek Haicman <mhaicman> |
| Severity: | low | Docs Contact: | |
| Priority: | low | ||
| Version: | 7.2 | CC: | ebenes, mhaicman, openscap-maint, plautrba |
| Target Milestone: | rc | ||
| Target Release: | --- | ||
| Hardware: | Unspecified | ||
| OS: | Unspecified | ||
| Whiteboard: | |||
| Fixed In Version: | openscap-1.2.4-1.el7 | Doc Type: | Bug Fix |
| Doc Text: | Story Points: | --- | |
| Clone Of: | Environment: | ||
| Last Closed: | 2015-11-19 12:09:38 UTC | Type: | Bug |
| Regression: | --- | Mount Type: | --- |
| Documentation: | --- | CRM: | |
| Verified Versions: | Category: | --- | |
| oVirt Team: | --- | RHEL 7.3 requirements from Atomic Host: | |
| Cloudforms Team: | --- | Target Upstream Version: | |
| Embargoed: | |||
|
Description
Martin Žember
2015-05-28 13:41:51 UTC
I agree that current README file is slightly outdated. We have greatly improved README.md file in the upstream repository and it will go to RHEL-7. However, I am afraid that we will not meet "Expected results" such: > Mention openscap-scanner subpackage This is an upstream README file. It is not possible to get there any information regarding downstream packaging. Does other components have documentation wrt downstream sub-packages? > Mention an existing profile or a way how to find one There are now profiles in OpenSCAP. Profiles are within scap-security-guide project. The best information wrt profiles can be found in `man scap-security-guide`. Would it make sense to add e.g. README.RHEL describing RHEL packaging and downstream changes? The expected result is not strict, let's reformulate it as high-level specifications what I would guess a user might expect: The information that is needed to run the oscap binary What is typically done when openscap is used There can be a link to a website or to a README.RHEL file but without it, I am not sure it makes much sense. Given that READMEs are often useless, I would personally not want to traverse through READMEs when looking for practical information. The user needs to know that there is a connection with SSG and that further information can be found by running `man scap-security-guide` (after he had installed it first). How about having a patch that adds all RHEL-specific information to the file? Does not make sense to me, Petr. Neither I want not add README.RHEL, nor I want a RHEL specific patch in the README.
This is not how we do things here. Red Hat spends a lot of time writing extensive documentation for each product. We want users to use this documentation. We have extra teams that make sure this documentation is well written, polished and makes overall sense.
You are right that readme's are often useless. That's why we try to build high quality prose.
Last year, I have spent a lot of time writing a verbose documentation for our RHEL customers. It is part of RHEL6 and RHEL7 Security Guide. You can find it at
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Security_Guide/chap-Compliance_and_Vulnerability_Scanning.html
It contains a lot of useful information on how to use OpenSCAP in context of Red Hat products. Please file a bugs against this documentation if anything is missing.
(In reply to Šimon Lukašík from comment #5) > ... > Last year, I have spent a lot of time writing a verbose documentation for > our RHEL customers. It is part of RHEL6 and RHEL7 Security Guide. You can > find it at > > > https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/ > html/Security_Guide/chap-Compliance_and_Vulnerability_Scanning.html > > It contains a lot of useful information on how to use OpenSCAP in context of > Red Hat products. Please file a bugs against this documentation if anything > is missing. What a great document! It is a pity that I did not know about it. How to make it more visible? BTW it says "To install oscap to your system, run the following command as root: ~]# yum install openscap-utils" which is in openscap-scanner currently. Nice catch. Could you please file a bug against Security Guide? (Please review rhel6 Security Guide as well and clone the bug if needed. Please also review existing bugs against this document. It might be know issue already. (In reply to Šimon Lukašík from comment #7) > Nice catch. Could you please file a bug against Security Guide? (Please > review rhel6 Security Guide as well and clone the bug if needed. Done, filed bz#1235647 and bz#1235648. Reviewed the new README.md file, minor changes suggested upstream. https://github.com/OpenSCAP/openscap/compare/maint-1.2...zemb:patch-1 Merged to upstream. Thanks Martin! Verified, README now does not contain obvious flaws. Regression suite passed. Since the problem described in this bug report should be resolved in a recent advisory, it has been closed with a resolution of ERRATA. For information on the advisory, and where to find the updated files, follow the link below. If the solution does not work for you, open a new bug report. https://rhn.redhat.com/errata/RHEA-2015-2356.html |