Firewalld

Tue Aug 26 20:23:39 UTC 2014

Well, I think both Stephen and Pete bring up good points.  Stephen mentions
the manageability of smaller guides but cautions against duplication of
content across multiple guides and suggests deep linking to help with
that.  Pete is concerned with the formats which would be used to
accommodate such a system as the one I was suggesting.

What we need is a Docs workflow that allows us to address both concerns.
We need modular documentation so that we do not duplicate content.  As
biologists seek to form natural groups in taxonomy (since they are stable
and predictable), we should do the same with our documentation; allowing
our content to develop in a structure which mirrors that of the software
used by Fedora will mean our documentation is created in units which have
predictable, stable boundaries (such as firewalld constituting a unit
rather than "Networking," whose boundaries and concepts will change as the
various underlying technologies go through their own often independent
changes).

It's much more manageable to document software packages, managing changes
to the documentation at that level, and then create guides which link those
modules of content together in pathways significant to the users.  To take
Pete's example of a web server configuration, a guide could be written
which would lay out the theoretical work to be done (configuring the
firewall, configuring the web application, configuring the mandatory access
control scheme) and the sections which explain the particular methods by
which one accomplishes those theoretical workloads can be deeply linked to
the content modules which describe the technologies currently used to
support those theoretical needs.

Now, with respect to Pete's point about documentation formatting, this
structure would lend itself to a workflow wherein the content modules are
supported most directly by the community via, perhaps, a wiki.  This likely
maximizes our harvest of community productivity (communities are good at
filling in explicit, testable, practical information) while reserving the
theoretical work for the Docs group (communities aren't necessarily as good
at filling that stuff in).  If we can put up a wiki with formatting which
easily (and hopefully, entirely automatically) converts to our current
documentation formats, and if the modular content is internally well
segmented, our guides can scoop up the content they need from the wiki at
the time of compilation.

My technical knowledge of the documentation platforms in use here is sadly
low, but it seems like it ought to be possible to have a wiki with
formatting guidelines that render the content modules ready for
assimilation into a guide.  Perhaps the Docs group could stub out the
sections in the wiki so that we have the structure we need in place and
then open up those sections to the general public for modification
(moderating as necessary, of course).

This seems like it might solve a lot of problems at once.  I know we should
be wary of huge unwieldy changes, but setting up a workflow to maximize
community participation while simultaneously reducing administrative
overhead and devoting those administrative resources to proper shepherding
of said community participation might give us an environment in which the
basic components of our documentation receive the dynamic attention
necessary to keep pace while the higher-level guides can be constructed
more easily and on demand, as the need for the guide (say, someone's desire
to make a website) arises.  If the platform is stable enough, high-level
documentation can be quickly regenerated to gather up the updates provided
from various communities (like those maintaining firewalld, Apache web
server, and SE Linux documentation) which might otherwise remain
disconnected and require a lot of administrative overhead just to get the
necessary communication going.

In short:  centralized, modular, community-supported base of documentation
combined with automated harvesting and gathering into higher-level
documentation which can be readily constructed and compiled on-demand.

If that sounds good to others, I guess the real question is still Pete's:
do we have features in our current documentation systems which will allow
for this, or do we need to find other systems, or is this too difficult to
orchestrate / how do we proceed from here?

-Dylan

On Tue, Aug 26, 2014 at 3:40 PM, Stephen Wadeley <swadeley at redhat.com>
wrote:

> On 08/26/2014 09:22 PM, Pete Travis wrote:
>
>> On 08/26/2014 09:43 AM, Eric H. Christensen wrote:
>>
>>> On Mon, Aug 25, 2014 at 03:40:10PM -0600, 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.
>>> >>
>>> > 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.
>>>
>>> So how about this...  Instead of having these big, fat guides that
>>> contain a lot of information on a lot of different topics, we start
>>> breaking down these guides into smaller chunks.  Think "Firewall
>>> Guide" which would talk specifically about iptables and firewalld.
>>> They likely would be less work to maintain (although there would be
>>> more of them) since, potentially, it would have less stuff to deal with.
>>>
>>> -- Eric
>>>
>>> --------------------------------------------------
>>> Eric "Sparks" Christensen
>>> Fedora Project
>>>
>>> sparks at fedoraproject.org - sparks at redhat.com
>>> 097C 82C3 52DF C64A 50C2  E3A3 8076 ABDE 024B B3D1
>>> --------------------------------------------------
>>>
>>
>> I like it. More manageable chunks sounds.. more manageable. Until we get
>> to the part where you have to read the httpd guide to set up a web
>> server, then the SELinux guide for file contexts for a web server, then
>> the firewall guide for firewall rules for a webserver -
>>
>
> Now now now Pete, steady on, having a small guide on firewall topics open
> while editing the firewall rules and then alt-tabing back to the guide you
> were using to set up httpd is not so bad. Could even be better than having
> a huge guide a having to search three or ten chapters forward and back all
> the time,
>
>
> or we maintain
>
>> the same content in different guides and try to keep track of it all.
>>
>
> No, please, no duplication. Links with scripts to check links are valid is
> better.
>
>> Yeah, I know you're saying "start here", but I think we've come back
>> around to the question about most suitable formats.
>>
>> The idea of modularized documentation is*really*  appealing, but the
>>
>> actual implementation isn't going to come for free.  Will
>> publican/docbook work? What formats would enable the built-for-purpose
>> articles that Dylan is envisioning?  We should explore some
>> possibilities before putting in the work to migrate the copy into new
>> books.
>>
>> ( He says, hoping the conversation doesn't die there )
>>
>> --
>> -- Pete Travis
>>   - Fedora Docs Project Leader
>>   - 'randomuser' on freenode
>>   - immanetize at fedoraproject.org
>>
>>
>>
>>
> --
> Stephen Wadeley
> Content Author | Red Hat, Inc.
> Purkynova 99 | Brno, Czech Republic
>
> --
> docs mailing list
> docs at lists.fedoraproject.org
> To unsubscribe:
> https://admin.fedoraproject.org/mailman/listinfo/docs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.fedoraproject.org/pipermail/docs/attachments/20140826/b02a203a/attachment.html>