You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@roller.apache.org by Dave Johnson <da...@rollerweblogger.org> on 2005/12/16 21:53:28 UTC
Draft of Roller 2.1 user guide
Updating the user guide via the wiki has always been a pain, plus we've
always wanted to ship a copy of the user guide with the release and
I've always wanted a nice paginated and printable user guide... so this
time I did the user guide in Open Office. I put the OpenOffice sxi file
and the exported a PDF, they're here for your review:
http://people.apache.org/~snoopdave/roller-user-guide-210.sxw
http://people.apache.org/~snoopdave/roller-user-guide-210.pdf
Comments and corrections are more than welcome.
- Dave
Re: Draft of Roller 2.1 user guide
Posted by Dave Johnson <da...@rollerweblogger.org>.
On Dec 17, 2005, at 12:56 PM, Anil Gangolli wrote:
> Nice doc!
>
> I think it's a step in the right direction to revision control docs
> with sources and versioning will be easier than before, but I think
> we'll still have some problems with this because the stored forms are
> basically binary blobs.
>
> I'd like to push gently in the direction of using a source form that
> is fundamentally text-based (XML, HTML or a wiki-based markup) and do
> all of the guides (user, installation, admin and configuration) in a
> uniform format. This will allow incremental contributions from more
> than one source, contributions from readers as patches, merging across
> branches, and understanding what's changed (or what wasn't updated) in
> the docs from release to release.
I don't know about you, but for a user guide, I would *much* rather use
a word processor than edit raw XML. Plus, getting tech writers to help
out might be a lot easier if we use friendly software like Open Office.
Open Office 2.0 uses ODF as it's native format and I believe there's a
XML version of that, but I wouldn't be surprised if the XML produced
does not produce useful SVN merges and diffs.
- Dave
Re: Draft of Roller 2.1 user guide
Posted by Dave Johnson <da...@rollerweblogger.org>.
On Dec 17, 2005, at 1:38 PM, Matt Raible wrote:
> Spring and Hibernate use DocBook. I agree that having a text-based
> format for documentation is important. I've had great success with
> JSPWiki and documentation for AppFuse - but that's only because so
> many people have participated. The tutorials alone (50 pages printed)
> have been translated to 5 languages! I don't think this type of
> cooperation could've happened with documentation stored in Subversion
> - but I could be wrong.
Since we've got the wiki locked down, folks can't edit the user guide
anyway. But when they get the user guide in Open Office format in the
distribution, they can easily edit and translate and submit back to us.
And JSPWiki doesn't produce nice paginated docs for printing
And we've been having all sorts of problems managing image attachements
in JSPWiki
- Dave
Re: Draft of Roller 2.1 user guide
Posted by Matt Raible <mr...@gmail.com>.
On 12/17/05, Anil Gangolli <an...@busybuddha.org> wrote:
>
> Nice doc!
>
> I think it's a step in the right direction to revision control docs with
> sources and versioning will be easier than before, but I think we'll
> still have some problems with this because the stored forms are
> basically binary blobs.
>
> I'd like to push gently in the direction of using a source form that is
> fundamentally text-based (XML, HTML or a wiki-based markup) and do all
> of the guides (user, installation, admin and configuration) in a
> uniform format. This will allow incremental contributions from more
> than one source, contributions from readers as patches, merging across
> branches, and understanding what's changed (or what wasn't updated) in
> the docs from release to release.
>
> Looking at the Hibernate docs (which I like) they appear to use
> Docbook and Apache FOP to get multi-page HTML, single-page HTML, and
> PDF from one source xml, but, to be honest, I don't have any experience
> with the formats and tools personally. Perhaps this is too long-term
> and ambitious a goal, but this is where I think we should be headed for
> documentation, at least in terms of general approach.
Spring and Hibernate use DocBook. I agree that having a text-based
format for documentation is important. I've had great success with
JSPWiki and documentation for AppFuse - but that's only because so
many people have participated. The tutorials alone (50 pages printed)
have been translated to 5 languages! I don't think this type of
cooperation could've happened with documentation stored in Subversion
- but I could be wrong.
Matt
>
> --a.
>
>
>
>
> Dave Johnson wrote:
>
> > Updating the user guide via the wiki has always been a pain, plus
> > we've always wanted to ship a copy of the user guide with the release
> > and I've always wanted a nice paginated and printable user guide... so
> > this time I did the user guide in Open Office. I put the OpenOffice
> > sxi file and the exported a PDF, they're here for your review:
> >
> > http://people.apache.org/~snoopdave/roller-user-guide-210.sxw
> > http://people.apache.org/~snoopdave/roller-user-guide-210.pdf
> >
> > Comments and corrections are more than welcome.
> >
> > - Dave
> >
> >
>
>
>
Re: Draft of Roller 2.1 user guide
Posted by Anil Gangolli <an...@busybuddha.org>.
Nice doc!
I think it's a step in the right direction to revision control docs with
sources and versioning will be easier than before, but I think we'll
still have some problems with this because the stored forms are
basically binary blobs.
I'd like to push gently in the direction of using a source form that is
fundamentally text-based (XML, HTML or a wiki-based markup) and do all
of the guides (user, installation, admin and configuration) in a
uniform format. This will allow incremental contributions from more
than one source, contributions from readers as patches, merging across
branches, and understanding what's changed (or what wasn't updated) in
the docs from release to release.
Looking at the Hibernate docs (which I like) they appear to use
Docbook and Apache FOP to get multi-page HTML, single-page HTML, and
PDF from one source xml, but, to be honest, I don't have any experience
with the formats and tools personally. Perhaps this is too long-term
and ambitious a goal, but this is where I think we should be headed for
documentation, at least in terms of general approach.
--a.
Dave Johnson wrote:
> Updating the user guide via the wiki has always been a pain, plus
> we've always wanted to ship a copy of the user guide with the release
> and I've always wanted a nice paginated and printable user guide... so
> this time I did the user guide in Open Office. I put the OpenOffice
> sxi file and the exported a PDF, they're here for your review:
>
> http://people.apache.org/~snoopdave/roller-user-guide-210.sxw
> http://people.apache.org/~snoopdave/roller-user-guide-210.pdf
>
> Comments and corrections are more than welcome.
>
> - Dave
>
>