On 08/25/2014 11:40 PM, Pete Travis wrote:
On 08/25/2014 02:17 PM, Eric H. Christensen wrote:
On Mon, Aug 25, 2014 at 01:13:46PM -0600, Pete Travis wrote:
Here's my idea: In the security guide, give an overview, instructions
on how to lock down to deny-all, general instructions on adding back,
and link out to the Networking Guide. In the NG, give a full overview -
network security should be an inherent part of network configuration.
In others, include the command to open a port for the service being
documented where appropriate.
I really dislike the idea of spreading information out into different
guides. Users think they've got the entire story only to miss another
aspect elsewhere.
I've gotten more and more frustrated over this problem. This is where
I see the wiki as being far superior to our guides. The ability to
easily share sections in guides is great. Perhaps this is a
discussion that should/could be had to figure out what we're losing by
staying with guides and what we're losing by hosting documentation on
the wiki.
Thoughts?
Oh, and to answer the question about whether it should go into the
Security Guide or the Networking Guide or the Admin Guide... maybe we
just need a good Admin Guide that explains how to do things securely
in the first place?
-- Eric
--------------------------------------------------
Eric "Sparks" Christensen
Red Hat, Inc - Product Security
sparks@xxxxxxxxxx - sparks@xxxxxxxxxxxxxxxxx
097C 82C3 52DF C64A 50C2 E3A3 8076 ABDE 024B B3D1
--------------------------------------------------
Right, it's the spreading out that bothers me too. Service config here,
network config here, firewall config there. I *don't* like the idea of
managing similar content in different places, though. The wiki doesn't
really fix that problem; includes work there just as well as in docbook,
there's just a broader scope. There are valid concerns about the
administrative overhead of our publishing stack, vs the 'just write'
ethos of a wiki - but I think that even with a wiki we would need to
have discussions about structure and scope.
Here are a few ideas for shared content, later I'll find out if they're
actually possible:
- Keep guide content as is, with more crosslinks. Use httpd redirects
to make maintenance easier, so in the guide we can link to
docs.fp.o/$LANG/latest_firewalld_instructions.html, which forwards to
the latest copy transparently, and we only have to get @sysadmin to
update the redirect file for each release. Possible SEO bonus.
- Enforce a directory tree on everyone's local machines, ie all guides
must live in the same folder. See if publican will traverse relative
paths above the document root, and add includes.
- See how far we can push entities. It worked for a full ulink tag when
we set up the BZ link, why not whole sections or admonitions? Keep the
shared content in a docs-includes.git and, uh, symlink the desired
entities file (ie firewall_stuff.ent, systemctl_stuff.ent) into each book.
- Dump everything into one big git repo, as Ben suggested. Messy :P
- Dump everything into one bug guide. Easier for us, not so easy for
readers.
- Find or write some magical solution where includes are easy and
trouble-free, outdated content is updated or reported automatically, and
writers are rewarded with their choice of beer, bacon, or something from
that other food group on commit.
In any case, I like the Security Guide, but I *don't* like the idea of
effectively treating security concerns as an afterthought. We want
people to think "Fedora Docs shows you how to make it secure the first
time" over "Fedora Docs has great instructions for $task, and there's
also a great security guide that probably tells you how to make $task
secure, but my service is set up now and maybe I'll read that later".
Oh, SELinux SELinux SELinux. Same thing there.
Dear Fellow Fedorians
I wrote the firewalld chapter for the RHEL 7 Security Guide, initially
based on a fedora wiki page.
I did write to Sparks in 2013 (05/24/2013) suggesting it might be of use
in the Fedora Security Guide. There have been some updates since then. I
could link to that from the Networking Guide if Sparks would like that.
Its easier for me if the Networking and Sys Admin Guides are similar to
the RHEL versions, but having an extra chapter or two, or less, is OK.
So I am not completely against having the firewalld chapter in the NG.
Duplicating content is to be avoided. If its just a paragraph then to
avoid sending the user off to another place you can duplicate a
paragraph. More than that, rather deep link to it. (jhradilek has
scripts to check links).
Making guides smaller and more focused is good. Hence the Networking
Guide was based on a few chapters split out from the System Admin Guide.
There are some other advantages in having more and smaller guides rather
then fewer and bigger guides. For example, you could have guides not
tied to a specific release; You could aim to publish the important
guides first; Smaller guides are easier for guide owners to manage.
Lets not start something that is unlikely to be finished.
Lets focus on tasks we are more familiar with and ask others to help
with things we are not familiar with. Which reminds me, I have some
urgent proofreading to do.
Regards
Stephen
--
Stephen Wadeley
Content Author | Red Hat, Inc.
Purkynova 99 | Brno, Czech Republic
--
docs mailing list
docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe:
https://admin.fedoraproject.org/mailman/listinfo/docs
