1:24 a.m.
I see this come up all the time, it's what you call a 'frequently
asked question.' People wonder ...
... are we replacing the wiki with a CMS?
... is the CMS for authoring content collaboratively?
... or is the CMS for publishing already completed documents in
various formats (Oo.org, XML, HTML, PDF, etc.)?
In my mind, the CMS is for putting publishing of formal content in the
hands of people who know and care. Writers should be able to publish
drafts and completed versions. Editors should be able to fix and push
updates. Translators should be able to complete, publish, fix, and
update translations of guides.
Our current system is essentially checking rendered content in to
source control, and an auto-builder puts it on the web. Historically,
this system was never well adopted, even by people who otherwise know
and understand the tools. Instead, easier to use tools have drawn the
attention and content, such as wikis and blogs. The adoption rates
are staggering by comparison.
The original purpose of getting a CMS was to make publishing easy. We
already have a toolchain and process for getting content out of the
minds of the subject matters experts, on to the wiki, in to DocBook
XML, translated, and rendered to HTML, PDF, etc. All of that can now
scale very well to larger and larger teams. The only missing piece is
the ability to take all that content and put it on
docs.fedoraproject.org.
I purposely did not address the idea of people actually collaborating
on content that has the CMS as canonical. When asked, we refer to the
upstream fedorahosted.com versioning system as the canonical source.
In this way, the CMS is similar to koji -- raw source turned in to
packaged content.
It is possible that a team would want to use the CMS as a working
location. I'm tempted to cross that bridge when it happens, an idiom
which here means, let's figure out how to make that work when we come
to that decision point.
Our choice(s) and experience with CMS systems is going to inform the
Websites team on possible CMS choices for running underneath
fedoraproject.org. In that case, the content there would probably
live inside of the CMS as canonical. People would collaborate on it
directly in the CMS.
It would be great if the CMS or some other tool would give a
collaborative, browser based wysiwyg editing experience for DocBook
XML that is in a version control system. There are as many reasons
why that won't work as there are to give it a try. In the meantime
...
Make things clearer? Muddier? Slightly filmy but clear enough to
drive?
- Karsten
--
Karsten 'quaid' Wade, Community Gardener
http://quaid.fedorapeople.org
AD0E0C41
1:42 a.m.
On Tue, Jan 27, 2009 at 12:54 PM, Karsten Wade <kwade(a)redhat.com> wrote:
Our current system is essentially checking rendered content in to
source control, and an auto-builder puts it on the web. Historically,
this system was never well adopted, even by people who otherwise know
and understand the tools. Instead, easier to use tools have drawn the
attention and content, such as wikis and blogs. The adoption rates
are staggering by comparison.
I am sure that I have missed this somewhere, but what are the specific
pain points that make the source_control_toolchain_builder driven
system not adoption ready ?
--
http://www.gutenberg.net - Fine literature digitally re-published
http://www.plos.org - Public Library of Science
http://www.creativecommons.org - Flexible copyright for creative work
3:47 a.m.
On Tue, Jan 27, 2009 at 01:12:15PM +0530, Sankarshan Mukhopadhyay wrote:
On Tue, Jan 27, 2009 at 12:54 PM, Karsten Wade
<kwade(a)redhat.com> wrote:
> Our current system is essentially checking rendered content in to
> source control, and an auto-builder puts it on the web. Historically,
> this system was never well adopted, even by people who otherwise know
> and understand the tools. Instead, easier to use tools have drawn the
> attention and content, such as wikis and blogs. The adoption rates
> are staggering by comparison.
I am sure that I have missed this somewhere, but what are the specific
pain points that make the source_control_toolchain_builder driven
system not adoption ready ?
You'd have to ask each individual what kept him/her from using the
s_c_t_b driven system, aka scm2web. That was how fedora.redhat.com
was organized for the first few years; that's the same code serving
docs.fp.org right now. When the wiki came online, *all* of the
activity on the f.r.c pages moved there within a matter of weeks.
What had been rarely and sparsely updated by a few was quickly a ghost
town.
By contrast, the wiki has hundreds of edits every single day. The
content growth is enormous and occasionally impressive. I'm
supposing, based on talking with people, that the easier tools are
all the difference.
Way back when we were deciding in Fedora Docs if we were going to
embrace or fight the wiki, I went to talk with Deb Richardson (dria),
who had just completed converting content and processes for Mozilla
developers. They had been formerly using DocBook XML in an SCM, and
converted entirely to a wiki-based content system. She described a
ten-fold increase in participation from hard-core developers who were
perfectly capable of picking up a simple markup language in a few
hours. They preferred instead to pick-up an even simpler markup
language in a few minutes, edit, and be done.
Ten-fold increase. Plus new people arrived who were interested and
passionate in doing the stuff no one had done to the XML. Organize,
edit, promote, watch every page to make sure things go OK.
So we eventually agreed to keep an eye on the wiki and maybe use it
sometimes. Since then, the experience in Fedora has been the same.
Except at our scale, it's more like a hundred-fold increase, probably
more.
The other lesson from that experience is, embrace the tools our wider
contributors are embracing. Don't try to tell them our specialized
tool is teh b0mb, we're a real documentation project, and that's the
way it is. Not unless we plan on paying people as the only way to get
contributors.
There is nothing about the current scm2web auto-publish system that a
few tool changes can't fix, but we're tired and under-staffed for
supporting a one-off, NIH content system. Rather than teach its
arcana to more people, I'd rather ditch it and move on.
That, at least, is my two-bits.
- Karsten
--
Karsten 'quaid' Wade, Community Gardener
http://quaid.fedorapeople.org
AD0E0C41
6:41 a.m.
On Tue, Jan 27, 2009 at 01:47:32AM -0800, Karsten Wade wrote:
[...a lot more than this, snip...]
There is nothing about the current scm2web auto-publish system that
a
few tool changes can't fix, but we're tired and under-staffed for
supporting a one-off, NIH content system. Rather than teach its
arcana to more people, I'd rather ditch it and move on.
Your previous posts are the clearest statements about Docs status in
recent memory. We just want people to be able to contribute
meaningfully in a way that makes sense to them.
* The wiki allows everyone to contribute with zero barrier to entry.
Write and publish immediately. Since anyone can write anything
there, caveat emptor.
* A CMS with an easy editor would basically be the equivalent of "a
wiki you can trust just a bit more," because there's an editorial
staff dedicated to it by virtue of it being the "official"
documentation site.
It might be important to note that the CMS is really an experiment,
something to try that we really haven't done yet. If it doesn't work,
the natural fall back might be to abandon all the editorial
mumbo-jumbo and simply concentrate solely on the wiki from there on
out. That's a bridge that can be crossed later too.
And of course, this is just my $0.02 as a Docs contributor. A lot of
the above is pure hogwash until (and unless) the next Docs leader
agrees.
--
Paul W. Frields http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
http://redhat.com/ - - - - http://pfrields.fedorapeople.org/
irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug
6:52 a.m.
Hi,
Doesn't the use of http://fedoraproject.org/w/api.php is good enough
for programming the final doc from the Wiki? considering what the
articles have been "selected" for the final doc!?
Rutu
--
regards,
Ruturaj K. Vartak
http://www.ruturaj.net
7:40 a.m.
On Tue, Jan 27, 2009 at 06:22:59PM +0530, Ruturaj wrote:
Doesn't the use of http://fedoraproject.org/w/api.php is good
enough
for programming the final doc from the Wiki? considering what the
articles have been "selected" for the final doc!?
I'm not sure if I understand your question correctly. Are you asking,
why don't we publish from SCM to the wiki? I think that's possible,
but doesn't get around the problem of making contributors to official
docs learn the $SCM in question.
--
Paul W. Frields http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
http://redhat.com/ - - - - http://pfrields.fedorapeople.org/
irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug
7:12 p.m.
I'll reply to the OP as well. In time.
Paul W. Frields wrote:
On Tue, Jan 27, 2009 at 01:47:32AM -0800, Karsten Wade wrote:
[...a lot more than this, snip...]
> There is nothing about the current scm2web auto-publish system that a
> few tool changes can't fix, but we're tired and under-staffed for
> supporting a one-off, NIH content system. Rather than teach its
> arcana to more people, I'd rather ditch it and move on.
>
Your previous posts are the clearest statements about Docs status in
recent memory. We just want people to be able to contribute
meaningfully in a way that makes sense to them.
This is software, nothing makes sense to most people. Computers are
complex and strange devices. Simple does not exist and never has.
* The wiki allows everyone to contribute with zero barrier to entry.
Write and publish immediately. Since anyone can write anything
there, caveat emptor.
"zero barrier" - This is a completely false assumption. I had to learn
wiki markup, it took me weeks. I still go back to the mediawiki help
section because it is not simple and straight forward. Easy for me is
NOT the same as easy for others. There is a barrier to entry involved in
every aspect of a documentation project. No one just wakes up in the
morning and instantly knows how to write in English either. Stop
assuming everyone has so much background knowledge.
* A CMS with an easy editor would basically be the equivalent of
"a
wiki you can trust just a bit more," because there's an editorial
staff dedicated to it by virtue of it being the "official"
documentation site.
Again, easy for you is not the same as easy for everyone. You, like me
most likely, have a strong background in computers and you have been
using them for several years. Most people's experience with "text
editors" is Microsoft Word anything else is complex and foreign.
"[dedicated] editorial staff " - Where are these editors coming from? At
the moment we are struggling to keep the contributers and writers we
have. Where are these (skilled and) dedicated editors coming from? Have
they been lurking around waiting for a chance to edit for several years?
It might be important to note that the CMS is really an experiment,
something to try that we really haven't done yet. If it doesn't work,
the natural fall back might be to abandon all the editorial
mumbo-jumbo and simply concentrate solely on the wiki from there on
out. That's a bridge that can be crossed later too.
An experiment which is generating a lot of email unproductively. Can I
ask this "is this getting any new documentation written?" Editing is a
colossal waste of time without any actual documents in a completed
state, ready for editing. This entire discussion is a waste of time.
And of course, this is just my $0.02 as a Docs contributor. A lot
of
the above is pure hogwash until (and unless) the next Docs leader
agrees.
My 0.05AUD of rage. I'm angry because the present process is rubbish.
Getting things published on fp.org is near impossible. Until this
process has less gates and walls hindering every attempt at pushing good
documentation into fedora I am keeping my upstream work with the project
sites(libvirt.org, ovirt.org, etc) who make it easy to publish documents
and don't waste my time.
My vote on this matter is don't add to the present quagmire but to tear
down the walls and free up fedora project. Any other upstream website is
simpler to publish to than fedoraproject at the moment.
Chris (Tsagadai)
7:10 p.m.
On Tue, Jan 27, 2009 at 3:17 PM, Karsten Wade <kwade(a)redhat.com> wrote:
[snipping off a very nicely written description]
There is nothing about the current scm2web auto-publish system that
a
few tool changes can't fix, but we're tired and under-staffed for
supporting a one-off, NIH content system. Rather than teach its
arcana to more people, I'd rather ditch it and move on.
Thank you for taking time to respond. It now makes sense.
--
http://www.gutenberg.net - Fine literature digitally re-published
http://www.plos.org - Public Library of Science
http://www.creativecommons.org - Flexible copyright for creative work
3:59 a.m.
Sankarshan Mukhopadhyay wrote:
On Tue, Jan 27, 2009 at 12:54 PM, Karsten Wade
<kwade(a)redhat.com> wrote:
> Our current system is essentially checking rendered content in to
> source control, and an auto-builder puts it on the web. Historically,
> this system was never well adopted, even by people who otherwise know
> and understand the tools. Instead, easier to use tools have drawn the
> attention and content, such as wikis and blogs. The adoption rates
> are staggering by comparison.
I am sure that I have missed this somewhere, but what are the specific
pain points that make the source_control_toolchain_builder driven
system not adoption ready ?
Not enough time in a day to waste on learning something like this. I
have been a active contributor via release notes but only on wiki edits.
Someone else has been doing the conversion into docbook xml and
publishing it.
Not that I don't know docbook xml or aren't aware of the benefits but it
is simply too tedious to do on a regular basis. a CMS would cut the
middlemen and let me publish directly, hopefully.
Rahul
3:59 a.m.
On Mon, 2009-01-26 at 23:24 -0800, Karsten Wade wrote:
It would be great if the CMS or some other tool would give a
collaborative, browser based wysiwyg editing experience for DocBook
XML that is in a version control system. There are as many reasons
why that won't work as there are to give it a try. In the meantime
...
Make things clearer? Muddier? Slightly filmy but clear enough to
drive?
Karsten,
Much clearer, in my opinion. Off the top of my head, I don't know
anything that does integrated version-controlling elegantly except for
MediaWiki, but I do not know if that's anyone's idea of an ideal CMS for
this purpose. But it's something to consider, and we already have a lot
of people experienced in using the Wiki, and many, many other projects
do use MediaWiki as their sole documentation engine.
________________________________________________________________________
Basil Mohamed Gohar
abu_hurayrah(a)hidayahonline.org
www.basilgohar.com
10:02 a.m.
On Mon, 2009-01-26 at 23:24 -0800, Karsten Wade wrote:
It would be great if the CMS or some other tool would give a
collaborative, browser based wysiwyg editing experience for DocBook
XML that is in a version control system. There are as many reasons
why that won't work as there are to give it a try. In the meantime
...
I think your post brought up a really good point, and one that I spent a
couple of hours wrestling with over the weekend, before throwing my
hands in the air in defeat.
Ideally (like you say above), the CMS would be *the* place to author,
edit, and render official documentation from the Fedora Docs team. The
more I thought about it though, them more I'm starting to lean *away*
from a CMS. Let me see if I can clearly articulate why.
1) Revision control. One of the things we'd like this CMS to do is to
provide revision control. So far, as I haven't seen a CMS that handles
revision control nearly as cleanly as either the wiki or using an SCM
system such as Subversion or git.
2) Document creation and editing. Ideally, we'd have a wysiwyg editing
tool in the CMS that would output perfectly valid DocBook. I don't see
this happening any time soon. This means that whatever we create inside
the CMS doesn't lend itself well to repurposing or to easy translation.
3) Translation. This is an area where most CMS systems do poorly as
well. How would we make this work with a CMS system? Check in the
primarly language version, along with the PO/POT files, and have the CMS
render the translated versions? Again, I think our current workflow has
a proven method that works, even if it's not highly automated.
To make a long story short, what if instead of concentrating on a CMS,
we concentrate on a system to take our
"created-in-the-wiki-converted-to-docbook-(and-optionally-translated)-and-rendered-to-HTML"
documents and easily publish them on the web? In other words, let's not throw out our
current system (with it's easy editing, working translations, and DocBook XML core).
Let's just take the parts that are the roughest (which I'm presuming are the
presentation parts) and fix those.
Make things clearer? Muddier? Slightly filmy but clear enough to
drive?
You certainly articulated the purposes of a CMS much more clearly than I
could ever hope to. I'm just not sure I've caught the vision of why a
CMS would be better than (most of) our current setup.
-Jared
2:48 p.m.
On Tue, Jan 27, 2009 at 11:02:04AM -0500, Jared Smith wrote:
Ideally (like you say above), the CMS would be *the* place to
author,
edit, and render official documentation from the Fedora Docs team. The
more I thought about it though, them more I'm starting to lean *away*
from a CMS. Let me see if I can clearly articulate why.
Well, ideal in an ideal world. :)
1) Revision control. One of the things we'd like this CMS to do
is to
provide revision control. So far, as I haven't seen a CMS that handles
revision control nearly as cleanly as either the wiki or using an SCM
system such as Subversion or git.
2) Document creation and editing. Ideally, we'd have a wysiwyg editing
tool in the CMS that would output perfectly valid DocBook. I don't see
this happening any time soon. This means that whatever we create inside
the CMS doesn't lend itself well to repurposing or to easy translation.
3) Translation. This is an area where most CMS systems do poorly as
well. How would we make this work with a CMS system? Check in the
primarly language version, along with the PO/POT files, and have the CMS
render the translated versions? Again, I think our current workflow has
a proven method that works, even if it's not highly automated.
I agree with you, and I think my clarifications still fall a half-step
short.
<vision role="Just Karsten's own opinion, YMMV, take with usual grain
of salt">
CMS doesn't handle revision control; that is for the upstream SCM on
fedorahosted.org
The Fedora Docs CMS is *not* for authoring content. The opposite is
probably true for a CMS used for other web properties
(www.fedoraproject.org.)
The Docs CMS is just a tool to put easy publishing in the hands of the
document writing teams.
Translation happens the same as always.
Document authoring continues as we've done -- some sourced in
wiki/sourced in fhosted.org => SCM => XML + PO => {HTML,PDF,RPM,TBZ,ZIP...}
The CMS should remove pain at the end of all the current processes
that are working fine. This pain is, "How do I publish and manage a
draft or final version of this document?"
</vision>
To make a long story short, what if instead of concentrating on a
CMS,
we concentrate on a system to take our
"created-in-the-wiki-converted-to-docbook-(and-optionally-translated)-and-rendered-to-HTML"
documents and easily publish them on the web? In other words, let's
not throw out our current system (with it's easy editing, working
translations, and DocBook XML core). Let's just take the parts that
are the roughest (which I'm presuming are the presentation parts)
and fix those.
It's really the publishing parts that are the roughest, and, yep,
that's what the CMS is supposed to fix.
The CMS is going to have a tonne of tools that we ignore or don't care
about or one day discover and love. Combined with programming, we may
end up adding to our capabilities. I don't consider any of that to
be our primary or secondary concern for a while.
In other words, if the CMS' authoring tools are so great that people
want to use them, they do use them, and we have a ton of content in
the CMS that needs translation, etc. ... *that is a good thing.* That
is the kind of problem I'd prefer to solve.
> Make things clearer? Muddier? Slightly filmy but clear enough
to
> drive?
You certainly articulated the purposes of a CMS much more clearly than I
could ever hope to. I'm just not sure I've caught the vision of why a
CMS would be better than (most of) our current setup.
It's not better than the good parts, it's additive. It *only*
replaces this:
http://cvs.fedoraproject.org/viewvc/web/html/?root=fedora
- Karsten
--
Karsten 'quaid' Wade, Community Gardener
http://quaid.fedorapeople.org
AD0E0C41
3:08 p.m.
On Tue, 2009-01-27 at 12:48 -0800, Karsten Wade wrote:
Document authoring continues as we've done -- some sourced in
wiki/sourced in fhosted.org => SCM => XML + PO => {HTML,PDF,RPM,TBZ,ZIP...}
Aha! OK, now I have a much clearer insight into what we're using the
CMS for.
The CMS should remove pain at the end of all the current processes
that are working fine. This pain is, "How do I publish and manage a
draft or final version of this document?"
OK, if this is the case (and trust me when I say that I'm relieved that
this is the case!), this brings up another set of questions:
1. How do we ensure that any editing that gets done in the CMS gets
pushed back to the authoritative DocBook? Should we make a rule that
*no* editing be done in the CMS, and that the CMS is merely for viewing
the final output of the process you described above?
2. How do we expect the CMS to handle multi-page HTML output from the
toolchain above? Typically, the XSL transforms our DocBook source into
either single-page HTML, multi-page HTML, or PDF documents. The one
that concerns me the most is multi-page HTML. Most CMS systems don't
take to kindly to importing a whole set of HTML pages, especially ones
that are all linked together and already have <head> elements, their own
stylesheets, etc. This point still makes me wonder if what we need is
really a CMS, or just some kind of HTML-set management utility.
-Jared
7:04 p.m.
On Tue, Jan 27, 2009 at 09:08:05PM +0000, Jared Smith wrote:
1. How do we ensure that any editing that gets done in the CMS gets
pushed back to the authoritative DocBook? Should we make a rule that
*no* editing be done in the CMS, and that the CMS is merely for viewing
the final output of the process you described above?
That is a good rule.
Think of the CMS as like the package repository.
If we do carry a patch on a package, there is a bugzilla report open
that explains why, and it doesn't close until the patch is upstream.
So, we'd want a similar policy. We might use the CMS to edit a
published document to get a fix up right away, but we'd want it tied
to a bug report that didn't close until the changes was ported to the
proper SCM instance.
2. How do we expect the CMS to handle multi-page HTML output from
the
toolchain above? Typically, the XSL transforms our DocBook source into
either single-page HTML, multi-page HTML, or PDF documents. The one
that concerns me the most is multi-page HTML. Most CMS systems don't
take to kindly to importing a whole set of HTML pages, especially ones
that are all linked together and already have <head> elements, their own
stylesheets, etc. This point still makes me wonder if what we need is
really a CMS, or just some kind of HTML-set management utility.
That's a good question. My expectation is that a CMS _could_ and
_should_ handle this case. (I just saw a Zikula module handle this.)
Maybe instead it imports the no-chunks (all-one-page) variety and then
chunks it itself inside of the CMS.
Or we autobuild from SCM to /srv/web/docs, then make container pages
in the CMS that link to the built per-lang PDF, HTML, etc. files.
OTOH, as you say, we may be looking for a different solution for this
publishing problem. I just don't want us coding it ourselves, that
would be 'Plan F for FAIL.'
- Karsten
--
Karsten 'quaid' Wade, Community Gardener
http://quaid.fedorapeople.org
AD0E0C41
5564
days inactive
5565
days old
13 comments
8 participants
participants (8)
-
Basil Mohamed Gohar -
Chris Curran -
Jared Smith -
Karsten Wade -
Paul W. Frields -
Rahul Sundaram -
Ruturaj -
sankarshan