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. -- -- Pete Travis - Fedora Docs Project Leader - 'randomuser' on freenode - immanetize@xxxxxxxxxxxxxxxxx
Attachment:
signature.asc
Description: OpenPGP digital signature
-- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/docs
