I have been a member of Docs for some time, mostly lurking helping out when I can try to mod when necessary... My 2 cents on this is that as I put in 4 hours of work and was nearly complete on a fairly large update to one of the guides, I noticed in the commit email that my work was for naught because the manual was removed from active duty, with nothing mentioned in any of the meetings... </rant>
Anyhow, heres my idea I just came up with since as mentioned direwalld is somewhat of a pain. I have successfully used it up until all these new feature came in and then things start breaking on me. How about this. I know this will sound like a major change (like it probably is), but what if we were to switch from a "guides" perspective and move to a Build Your Own Manual based on selecting Chapters (i.e. mini guides, or some other method...), and having a system build into a guide.
As an example, one could choose from a "Security" section on how Not to disable SELinux and survive or A Basic Introduction to firewalld and maybe firewalld to Make Your Brain Explode and generate a guide that works for the user. I know publican is crying over this idea, (but perhaps that's just revenge as I tried and never decided to like working with it).
Perhaps working with Docs as a collection of vetted docs that can be selected and compiled as needed, if there is a regular occurrence we can make a Favourites (or Favorites) section that gets managed by the Documentation Team. This way the wiki style bites of information can be beefed out and then... well I think the point is made.
If this is worth really fleshing out let me know and I will invest some time.
Regards
Bryan
On Mon, Aug 25, 2014 at 5:40 PM, Pete Travis <me@xxxxxxxxxxxxxx> wrote:
On 08/25/2014 02:17 PM, Eric H. Christensen wrote:> -- Eric
> 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?
>
>Right, it's the spreading out that bothers me too. Service config here,
> --------------------------------------------------
> Eric "Sparks" Christensen
> Red Hat, Inc - Product Security
>
> sparks@xxxxxxxxxx - sparks@xxxxxxxxxxxxxxxxx
> 097C 82C3 52DF C64A 50C2 E3A3 8076 ABDE 024B B3D1
> --------------------------------------------------
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
--
docs mailing list
docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe:
https://admin.fedoraproject.org/mailman/listinfo/docs
-- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/docs
