12:16 a.m.
Here are some of my thoughts on how we can make fedora-docs a better place.
First off I think we would benefit from a simpler docs model which
simulates the documentation model of real world publishing.
For instance instead of this entire page:
http://fedoraproject.org/wiki/DocsProject/WorkFlow
We:
1. Use the wiki as a wiki. Wikis are great for short howtos and
explanations. However, they quickly become unwieldy when trying to do
anything else. Sure you can play Zork on uncyclopedia but that isn't the
purpose behind a wiki.
2. Replace the old publishing workflow with this:
1. Develop content in small groups, pulling useful howtos and snippits
from the wiki and expanding them. Correct and copy edit wiki articles to
help development. For small stand alone sections, write on the wiki
first and get them reviewed. Or do none of those things and just write
in Docbook XML. after all, this is open source and we are all about
choice, do what you want as long as you contribute :) fedoraproject.org
can host the XML in your favourite repository system.
2. Write a daemon that publishes Docbook XML using publican to
fedoraproject.org/docs
3. ???
4. Profit
All comments appreciated.
Chris
1:22 a.m.
Christopher Curran wrote:
Here are some of my thoughts on how we can make fedora-docs a better
place.
First off I think we would benefit from a simpler docs model which
simulates the documentation model of real world publishing.
For instance instead of this entire page:
http://fedoraproject.org/wiki/DocsProject/WorkFlow
We:
1. Use the wiki as a wiki. Wikis are great for short howtos and
explanations. However, they quickly become unwieldy when trying to do
anything else. Sure you can play Zork on uncyclopedia but that isn't
the purpose behind a wiki.
2. Replace the old publishing workflow with this:
1. Develop content in small groups, pulling useful howtos and snippits
from the wiki and expanding them. Correct and copy edit wiki articles
to help development. For small stand alone sections, write on the wiki
first and get them reviewed. Or do none of those things and just write
in Docbook XML. after all, this is open source and we are all about
choice, do what you want as long as you contribute :)
fedoraproject.org can host the XML in your favourite repository system.
2. Write a daemon that publishes Docbook XML using publican to
fedoraproject.org/docs
3. ???
4. Profit
All comments appreciated.
Chris
No one thinks a simpler system is good, or bad?
Chris
3:56 a.m.
I think the CMS was supposed to help with this. See the various CMS
related threads (I am sure someone has a link?).
<http://icanhascheezburger.files.wordpress.com/2008/10/funny-pictures-cat-...
1:51 p.m.
On Mon, Feb 09, 2009 at 05:22:16PM +1000, Christopher Curran wrote:
No one thinks a simpler system is good, or bad?
Here's the ironic part -- the system you describe is very much like
the system we have been using for the past few years. (Close enough,
anyway.)
As I've mentioned before, the process pages are full of cruft and are
hard to understand for new and experienced contributors. Improvement
needed. I am an OK person to work on that, but also think someone a
bit newer might do a better job. No foul for it being unclear as you
read it, right?[1]
I think the difference of opinion that we are balancing on is the idea
of using the wiki as a primary/initial authoring tool for some
documents. Because of the 1000x more contributors to the wiki, it is
currently a better way to get the wider community involved in
documenting. It doesn't mean we bow to the will of the wiki, but it
has to be a serious part of the equation.
One reason we have subtle variations is precisely because people such
as yourself come along and want to treat their upstream document in
their own way. A team wants to work on a new document entirely in
DocBook XML, great! A team wants to work in wiki first, then convert,
great! OO.org then convert to DocBook XML, great! For the most part,
you'll notice, DocBook is the integration point, even if it is not
always canonical.
In addition, some documents lend themselves to variations. For
example, the User Guide is a good document for a larger group of new
contributors to collaborate on via the wiki. It is worth starting
each new version back on the wiki. At the end of the writing, the
conversion for each version to XML ends up teaching them more about
DocBook XML. This is because the conversion from MediaWiki produces a
set of working XML files, and the conversion team is focused on inline
XML markup. In the future, the team might choose to stay in XML,
great!
The release notes are a third variation. At one time, we considered
the wiki canonical throughout the process, but that proved to be too
much of a PITA. This last release, we made the XML on
fedorahosted.org/release-notes canonical after the conversion.
Because the content is 80% new for each release, we have gone back to
clean beat pages to author for each release to gain the collaboration
force multiplier.
Thanks - Karsten
[1] As a note, the original steps you wrote at the start of the thread
presume a bit of back knowledge. It also compresses out the actual
processes involved in each of those content development methods. For
me, I am at my most unclear when I start to write out al those
details. I think that is part of why [[DocsProject/WorkFlow]] is so
unclear.
--
Karsten 'quaid' Wade, Community Gardener
http://quaid.fedorapeople.org
AD0E0C41
7:07 p.m.
Karsten Wade wrote:
On Mon, Feb 09, 2009 at 05:22:16PM +1000, Christopher Curran wrote:
> No one thinks a simpler system is good, or bad?
>
Here's the ironic part -- the system you describe is very much like
the system we have been using for the past few years. (Close enough,
anyway.)
No, no it's not. The present system has several manual stages and
several superfluous stages. That entire CVS to PHP to old docbook system
is a prime example of why there is nothing even remotely alike about
what I proposed and what currently exists.
As I've mentioned before, the process pages are full of cruft and
are
hard to understand for new and experienced contributors. Improvement
needed. I am an OK person to work on that, but also think someone a
bit newer might do a better job. No foul for it being unclear as you
read it, right?[1]
Sure, which is why I advocate chopping it back. I think the first step
should be to draw a flow diagram using inkscape or the gimp and see
exactly what the process is versus what we want. Every process page
needs a flow diagram so all people working on the project can clearly
define where they sit in the development life cycle.
I think the difference of opinion that we are balancing on is the
idea
of using the wiki as a primary/initial authoring tool for some
documents. Because of the 1000x more contributors to the wiki, it is
currently a better way to get the wider community involved in
documenting. It doesn't mean we bow to the will of the wiki, but it
has to be a serious part of the equation.
I wasn't saying we drop the wiki or not acknowledge it's presence. The
key difference in what I am saying is writing books is not writing a
wiki. A wiki cannot replace author collaboration, it is the wrong tool.
No author, past or present has penned their tome on a wiki. That's not
to say that the wiki is not important just that it should not be
considered THE place for writing books.
One reason we have subtle variations is precisely because people
such
as yourself come along and want to treat their upstream document in
their own way. A team wants to work on a new document entirely in
DocBook XML, great! A team wants to work in wiki first, then convert,
great! OO.org then convert to DocBook XML, great! For the most part,
you'll notice, DocBook is the integration point, even if it is not
always canonical.
I have no issues with how a team works. My issue is with the complexity
of the publishing method. Right now it is quite hard to go from Docbook
to hosted content. That is where we need the most revision of present
practices. Regardless of the complexity involved it should be a one step
push. Documentation projects should be pre-approved to push updates to
the hosted content. Documentation projects need to be treated more as
stand alone projects which publish to fedora docs project rather than
work in subjugation to.
In addition, some documents lend themselves to variations. For
example, the User Guide is a good document for a larger group of new
contributors to collaborate on via the wiki. It is worth starting
each new version back on the wiki. At the end of the writing, the
conversion for each version to XML ends up teaching them more about
DocBook XML. This is because the conversion from MediaWiki produces a
set of working XML files, and the conversion team is focused on inline
XML markup. In the future, the team might choose to stay in XML,
great!
Nothing in my proposal excluded such a team from working that way.
Again, what I am arguing for is simpler publishing.
The release notes are a third variation. At one time, we considered
the wiki canonical throughout the process, but that proved to be too
much of a PITA. This last release, we made the XML on
fedorahosted.org/release-notes canonical after the conversion.
Because the content is 80% new for each release, we have gone back to
clean beat pages to author for each release to gain the collaboration
force multiplier.
This is low level detail to distract from what I am saying.
Thanks - Karsten
[1] As a note, the original steps you wrote at the start of the thread
presume a bit of back knowledge. It also compresses out the actual
processes involved in each of those content development methods. For
me, I am at my most unclear when I start to write out al those
details. I think that is part of why [[DocsProject/WorkFlow]] is so
unclear.
Also RE: Murray
The CMS is Yet Another Markup and Yet Another step in an abysmally long
chain. What we need is an automated tool to publish work from
documentation projects.
The entire argument about making editing easier is stupid. Editing is
hard. The generic open source method for edits and corrections is filing
bugs. This works just as well for documentation projects as it does for
kernels. I know the impulse of software development is to reinvent the
wheel and call it something new but it is wrong. If we continue to think
that using a CMS will fix anything we are just deluding ourselves. What
we need is a publishing tool. Nothing else will fix our present problems
other than a publishing tool.
Chris
7:20 p.m.
No, no it's not. The present system has several manual stages and
several
superfluous stages. That entire CVS to PHP to old docbook system is a prime
example of why there is nothing even remotely alike about what I proposed
and what currently exists.
You do not have to convert to PHP. make html, then copy into working
copy of /cvs/fedora/, then commit. Of course, it is easy to say that
once you have done it before, but the documentation tells you how to
do everything (as long as you ignore the PHP bits ;-)):
<http://docs.fedoraproject.org/documentation-guide/en_US/ch-publishing.htm...
7:21 p.m.
although, I did find the whole process a pain and hard to do the first
time...but I have no ideas on how to fix that *^_^*
6:43 a.m.
On Tue, Feb 10, 2009 at 11:07:16AM +1000, Christopher Curran wrote:
Sure, which is why I advocate chopping it back. I think the first
step
should be to draw a flow diagram using inkscape or the gimp and see
exactly what the process is versus what we want. Every process page needs
a flow diagram so all people working on the project can clearly define
where they sit in the development life cycle.
This is a pretty good idea -- it helped when I was working with John
Poelstra on the Feature process pages to see the workflow for the
process he had in mind.
[...snip...]
I have no issues with how a team works. My issue is with the
complexity
of the publishing method. Right now it is quite hard to go from Docbook
to hosted content. That is where we need the most revision of present
practices. Regardless of the complexity involved it should be a one step
push. Documentation projects should be pre-approved to push updates to
the hosted content. Documentation projects need to be treated more as
stand alone projects which publish to fedora docs project rather than
work in subjugation to.
[...snip...]
Also RE: Murray
The CMS is Yet Another Markup and Yet Another step in an abysmally long
chain. What we need is an automated tool to publish work from
documentation projects.
I'd swear that you sound like someone who's getting ready to sell us
an automated tool to publish to hosting. I'm not saying I for one
would turn it down. But would you care to just go ahead and put it on
the table so we can look at it and figure out the next steps?
The entire argument about making editing easier is stupid. Editing is
hard. The generic open source method for edits and corrections is filing
bugs. This works just as well for documentation projects as it does for
kernels. I know the impulse of software development is to reinvent the
wheel and call it something new but it is wrong. If we continue to think
that using a CMS will fix anything we are just deluding ourselves. What
we need is a publishing tool. Nothing else will fix our present problems
other than a publishing tool.
In other words, you want the Fedora Docs Project to do things the same
way that you do them in Red Hat Engineering Services. That's
understandable and a valid PoV. But if we have to do that to get your
positive input and all of our volunteers disappear, that's a pretty
high price to pay.
My hope is that we can have both, but to do that you need to go past
the idea stage, as have the folks who are working with the Zikula
crew. Put the tool on the table (or some level of detail that you
envision). Work with the Infrastructure team to get a test instance
on one of the publictest servers, so we can weigh one workflow against
the other. Based on what you're saying, it should be pretty clear if
the CMS really isn't helping as much as a publishing tool.
--
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
8:05 a.m.
I'd swear that you sound like someone who's getting ready to
sell us an
automated tool to publish to hosting. I'm not saying I for one would
turn it down. But would you care to just go ahead and put it on the
table so we can look at it and figure out the next steps?
There's someone on the Zikula team writing a module to pull your XML
documents from source control and publish them into the CMS for displaying
to the world. We're already working on that, in case it hasn't been clear
previously. If this isn't useful or needs to change best to let us know
while the script is still in the early stages.
Theoretically you simply write your docbook XML, commit it when you're done
and then log into the CMS and hit publish to update the documents.
Hopefully there will also be a test option where you can publish in a
private location for checking while avoiding publishing a part finished
document to the public at large.
10:03 a.m.
On Tue, Feb 10, 2009 at 02:05:08PM -0000, Simon Birtwistle wrote:
> I'd swear that you sound like someone who's getting
ready to sell us an
> automated tool to publish to hosting. I'm not saying I for one would
> turn it down. But would you care to just go ahead and put it on the
> table so we can look at it and figure out the next steps?
There's someone on the Zikula team writing a module to pull your XML
documents from source control and publish them into the CMS for displaying
to the world. We're already working on that, in case it hasn't been clear
previously. If this isn't useful or needs to change best to let us know
while the script is still in the early stages.
Theoretically you simply write your docbook XML, commit it when you're done
and then log into the CMS and hit publish to update the documents.
Hopefully there will also be a test option where you can publish in a
private location for checking while avoiding publishing a part finished
document to the public at large.
I had read about this module, and just to clarify, I don't want to
throw a spanner/wrench into anyone's works. I think this sounds just
like what Chris is recommending -- a one-click publish to hosting
solution. If there are alternate solutions available, happy to see
them.
--
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:33 p.m.
On Tue, Feb 10, 2009 at 11:03:33AM -0500, Paul W. Frields wrote:
On Tue, Feb 10, 2009 at 02:05:08PM -0000, Simon Birtwistle wrote:
> > I'd swear that you sound like someone who's getting ready to sell us
an
> > automated tool to publish to hosting. I'm not saying I for one would
> > turn it down. But would you care to just go ahead and put it on the
> > table so we can look at it and figure out the next steps?
>
> There's someone on the Zikula team writing a module to pull your XML
> documents from source control and publish them into the CMS for displaying
> to the world. We're already working on that, in case it hasn't been clear
> previously. If this isn't useful or needs to change best to let us know
> while the script is still in the early stages.
>
> Theoretically you simply write your docbook XML, commit it when you're done
> and then log into the CMS and hit publish to update the documents.
> Hopefully there will also be a test option where you can publish in a
> private location for checking while avoiding publishing a part finished
> document to the public at large.
I had read about this module, and just to clarify, I don't want to
throw a spanner/wrench into anyone's works. I think this sounds just
like what Chris is recommending -- a one-click publish to hosting
solution. If there are alternate solutions available, happy to see
them.
With the same conditions that brought Zikula here -- a team of people
need to deploy and maintain a solution, not throw ideas over the wall
to see what sticks.
Since Zikula is right now doing *exactly what Chris is asking for* and
it's going to also give us handy WebUI content management for all
those who prefer that over ... well, however the automated publishing
tool in Chris' vision lets team members decide where and when to
publish ... plus there is momentum over _here_ for Zikula ... uh, what
are we arguing about again?
- Karsten
--
Karsten 'quaid' Wade, Community Gardener
http://quaid.fedorapeople.org
AD0E0C41
5554
days inactive
5560
days old
10 comments
5 participants
participants (5)
-
Chris Curran -
Karsten Wade -
Murray McAllister -
Paul W. Frields -
Simon Birtwistle