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@xxxxxxxxxx> wrote:
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,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@xxxxxxxxxxxxxxxxx - sparks@xxxxxxxxxx
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 -
No, please, no duplication. Links with scripts to check links are valid is better.
or we maintain
the same content in different guides and try to keep track of it all.
Yeah, I know you're saying "start here", but I think we've come backThe idea of modularized documentation is*really* appealing, but the
around to the question about most suitable formats.
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@xxxxxxxxxxxxxxxxx
--
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
-- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/docs
