Basil Mohamed Gohar wrote:

So, is it asking a lot to delineate precisely what are the things the Docs project does/produces, so that maybe we - or, at the very least, I

• can, collectively (or solitarily) understand that maybe we use this

tool/process for that, and that tool/process for this?

One way to get a sense for the major tasks and work products is to look at the schedule. http://poelstra.fedorapeople.org/schedules/f-11/f-11-docs-tasks.html

I'll let someone else speak to the exact work products as I'm not an official docs person though I help maintain the schedule :)

John

Karsten Wade wrote:

On Tue, Jan 27, 2009 at 11:51:29AM -0500, David Nalley wrote:

...

Sparks, jsmith and I were talking in IRC and I thought the conversation should have a bit wider audience.

I think that while kbase and housing documentation for packaging guidelines and legal are excellent use cases for a CMS, I wonder if by trying to use it for everything we are not trying to use a hammer to drive a screw. My reason for saying that is that it seems like we are trying to push all of our non-wiki documentation into the CMS, which at least from my perspectives means we, to one degree or another, are abandoning DocBook.

For our 'heavy' documents, such as Release Notes, User Guide, and Security Guide, I don't see an escape from DocBook - it provides a lot of advantages that just don't exist in a CMS. It does have disadvantages to be sure, but I guess the question in my mind is with all of the talk of moving to a CMS are we really prepared to ditch DocBook and it's benefits? Or is the CMS a solution for things like Legal and Packaging Guidelines, and potentially a knowledgebase, and not more?

Thoughts, Comments, Flames?

I think all of this was answered in my responses to other threads.

We have to consider a document as coming from an upstream. The team working on the document can choose from a wide variety of content solutions --

What upstream? We are just going to loot other distros docs now because they manage to get stuff published?

• fp.org/wiki
• fhosted.org/$foo/wiki
• fhosted.org/$foo/$xml
• docs.fp.org/$cms (they will, you know they will)

So four solutions is how to ensure consistency...

To some degree, this Docs Project team needs to think of itself as packagers. Some content we package we produce ourselves; some we get from upstreams. Where we control the full lifecycle, we make certain choices. Where we cannot control the full lifecycle, we take what we get and do what we need to it.

What lifecycle? Most docs projects are stagnant wiki pages? Models are great when there is real development going on but a hindrance when there isn't.

We 100% should have a consistent, best-practice, preferred, and documented set of tools and process to take ideas to published.

Absolutely. That means one(1) solution. The kernel is almost entirely written in C and managed with git repositories. They don't have 14 repository types and 10 different languages. Consistency is one size fits all. Only git and DocBook would be a consistent fedora docs project. Any other system is inconsistent by definition.

We also need to accomodate the many places content is coming from and not expect that we can enforce (all of) our styles on them.

You keep talking about content coming from places as if it actually is coming in. Last I looked there were two(2) documents actually being produced: the security guide and the release notes. Perhaps two is many in your world but most people's definition of many is more than that.

There is a balance in here; from experience we can know "All DocBook XML following this specific standard in our single version control system" does not scale to support something the size of the Fedora Project, much less just Fedora Linux.

Bull. It scales well with other projects. Referencing gentoo again because it is where I used to do a lot of documentation. Single SVN repo and GuideXML. They have several orders of magnitude more content than fedora project.

It simply doesn't scale with your desire to have fingers in every pie.

Chris

On Wed, 2009-01-28 at 11:49 +1000, Christopher Curran wrote:

What lifecycle? Most docs projects are stagnant wiki pages?

I respectfully disagree on this point. Maybe I should take a moment to explain that when the Fedora Docs Project talks about their documentation, they're often referring to the formal documents (Release notes, Security Guide, Software Management Guide, User Guide) as well as the more informal documentation on the wiki. In the case of formal docs, we aim to provide leadership and oversight on the process, while in the case of the informal documents on the wiki, our aim is to be more of a gardener, not a gatekeeper.

In the case of some of these formal documents, the source is the wiki, and our "lifecycle" is to convert the wiki to DocBook, and from there do editing, translation, and publishing to HTML/PDF, and publishing on the web. (As an aside, doing the conversion from wiki -> DocBook is one of the pieces I most enjoy and find my time is most valuable to the project.) Other formal documents started their life in some other format, often times already being in DocBook format. The same workflow still applies, however... with editing, translation, format conversion, and publishing.

In the case of the informal documents, their entire lifecycle is most likely to be spent on the wiki.

Also, to call the wiki pages stagnant is a bit of a stretch. There's a lot happening in a lot of different places on the wiki (both directly related to the docs project and otherwise), and I think it's incongruous to paint the entire wiki with a broad brush and call it stagnant.

You keep talking about content coming from places as if it actually is coming in. Last I looked there were two(2) documents actually being produced: the security guide and the release notes. Perhaps two is many in your world but most people's definition of many is more than that.

There are a number of documents coming in. I alone have worked on the release notes, the installation guide, the software management guide, and the user guide in the past few months, along with many of informal docs on the wiki.

It may not compare to the number of docs you juggle in your <dayjob/>, but that doesn't mean we're not working, as your post implies.

-Jared

I'm actually surprised at Christopher's assessment of the situation. Is it disingenuous? He works in Red Hat's Content Services group, I assumed he was aware of the ongoing work from that group to fully open content that has been only on redhat.com to date.

https://fedorahosted.org/securityguide/ https://fedorahosted.org/selinuxguide/ https://fedorahosted.org/deploymentguide/

[snip]

I haven't added up the number of pages, but it's more than nothing. Consider that all but the first items from Red Hat were developed entirely in the community.

Sorry to complain :-) "https://fedorahosted.org/selinuxguide/" was developed entirely in the community. See the archives:

http://www.nsa.gov/research/selinux/list-archive/index.shtml

The SELinux User Guide is not on http://www.redhat.com/docs/manuals/enterprise/.

I might have missed what you were saying, and the community reference above may be referring to fedora documentation or fedora specific mailing lists only. Also, "selinuxguide" may have been referring to Red Hat Enterprise Linux 4?

Cheers.