On Fri, Jan 16, 2009 at 10:31:54AM +1000, David O'Brien wrote:
>
I'm working on a project that currently produces a community version and
an Enterprise version of both the software and the documentation. The
community version of the documentation is written and maintained on a
wiki, and the Enterprise doc using DocBook xml. Being the only writer on
the project means the community version of the doc is always out of date
(I focus on Enterprise doc). This is a new project and community
engagement is still developing. Maintaining both versions of the doc to
keep up with the software is not possible for a single writer, and quite
frankly not desirable. I'm researching how I might develop all of the
doc in a single language (DocBook xml) and deliver it to both
destinations using publican.
One of the reasons we embraced the wiki is because it greatly
increased the community contributions. Be aware that limiting source
to DocBook XML also limits the number of contributors.
This is of course without the Magic Grail that we all want -- an easy
way similar to a wiki or wysiwyg-via-WebUI that reads and writes to
valid DocBook XML.
In the meantime, by moving to stand-alone repositories for each guide
on
fedorahosted.org, it pushes more in tools and decision making to
the individual contributor teams. It's really easy for each guide to
set its own policy on contributions and processes for the canonical
source.
I found a bunch of info on the website about community contributions
and
the use of WikiText, OOo, plain text, etc., if they weren't comfortable
with the idea of using xml. I'm looking into whether supporting
contributions in a wide range of formats is feasible.
It takes a team, in our experience so far. Some of what you read is
outdated; we're busy working on renaming, categorizing, and cleaning
up that content. In general, we support:
* Wiki-only for shorter how-to/tutorials maintained inside and outside
of Fedora Docs Project.
* Wiki that gets converted to XML when it's ready for translation
(Release Notes does this, several other guides have undergone this
transition.) In this case, usually each version is worked via the
wiki first.
* DocBook XML-only content (Installation Guide, Security Guide).
These are full-length books that are not worth pushing back and
forth to the wiki. The wiki is lossy; you lose contextual meaning
to the mark-up.
I didn't determine from what I read at what point contributions
are
reviewed. (I didn't read the whole site, of course, just looked for the
important bits.) Are reviews performed on WikiText, converted DocBook,
elsewhere? How do you determine who can review and approve docs? How do
you manage docs that have been submitted, converted, and published? Are
edits/updates performed in WikiText and reconverted?
Probably the best overall page, still sure to have some inaccuracies:
https://fedoraproject.org/wiki/DocsProject/WorkFlow
1. Group collaborates on wiki content:
* Beats for Release Notes are technology specific sections to be
included in larger chapters.
* One chapter per wiki page for guides written on the wiki.
2. Content is ideally edited as it is written. Writers learn as they
go how to improve their writing. Editors don't save all the work
for the end. All this work happens in the wiki.
3. When content is ready for translation-then-publication, it is
converted to DocBook XML in either the fedora-doc-utils or publican
toolchains.
4. Translated and base-language versions are published on
docs.fedoraproject.org.
What degree of sharing occurs between Fedora and RHEL documentation
(if
any)? How is this handled?
Historically there has not been any, save an occasional release note.
To catch an opportunity like this, someone needs to be willing to lead
the effort on the document. This means trading writing and editing
for project management, growing trust in others to do the write/edit
work.
There has to be an upstream somewhere that we can use. One method is
to put the upstream content inside of Fedora. It is then usable by
downstreams such as RHEL. This has not happened so far.
Currently, there are several guides available or soon available as
stand-alone upstream projects on
fedorahosted.org. In this case,
Fedora is as much a downstream as RHEL and CentOS are.
In the case of FreeIPA content, for example, I would expect the latter
situation would probably occur. We could want to use some or all of
the FreeIPA content in, for example, a Fedora Deployment or Fedora
Administration Guide. Downstream appliance makers could use:
(FreeIPA + Fedora) - (cruft) - (Fedora mark) + (Fedora Remix mark)
- Karsten
--
Karsten 'quaid' Wade, Community Gardener
http://quaid.fedorapeople.org
AD0E0C41