PDF vs. Doc project comparison
5 views
Skip to first unread message
Gregory Brown
Mar 30, 2008, 10:20:50 PM3/30/08
to RubyMendicant
Hi,
As requested I've put together a sort of analysis of the PDF project
vs. the documentation project.
The way it looks now is that a PDF::Writer rewrite is the project to
beat. Though some have mentioned they don't personally have a use for
it, most of them agree it is a worthwhile project and would be willing
to support it. Many have indicated this project seems like the most
likely to succeed among my ideas. Given that the task would be to
implement a software library based on a well defined specification,
and the fact that we already have a sense of what some of the
challenges involved with this are, I tend to agree.
However, I still think the documentation project has a lot of merit.
If in the next couple days, it seemed like we got together a clear
plan for the kinds of topics we'd be covering and how the project
would progress, it remains to be a possibility. I definitely am
holding some reservations about this though, because very few people
have come up with concrete ideas about this project, and that makes me
nervous.
Below, you'll see my current thoughts about the pros and cons of each
project. Please feel free to speak up and let me know what you are
thinking. Essentially, if we can't get together at least the
beginnings of a clear plan for the documentation project by April 2nd
or so, I think I'll go with the PDF project. However, if we can get
the doc project ideas organized and I can get a sense of the
community's support for it, it still has a chance.
So... silence gets you PDF, some well thought out cajoling might get
you many months of documentation work. :)
Analysis of the projects follows.
-greg
###########################
=== First Class PDF Support in Ruby
The goal of this project would be to write a tiny, fast, and beautiful
PDF writing library for Ruby. This project would support Ruby 1.9 and
m17n from
the ground up, eliminating two serious issues for those currently
generating
PDFs in Ruby.
Ideally, this project could replace PDF::Writer in the near future.
PROS:
- This is a complicated project that is unlikely to get worked on in
people's
spare time, which means it is somewhat ideal for Ruby Mendicant.
- As one of PDF::Writer's principal maintainer's, learning more about
PDF
will be helpful immediately to me, and PDF::Writer's users.
- Ruby 1.9 deserves third party library support
- A new PDF writing package would open up a lot of possibilities for
Ruby
Reports (Ruport), as well as simplify porting Ruport to Ruby 1.9
- Currently the most popular project idea for Ruby Mendicant
- Forms a complete, extremely well defined project (due to the PDF
spec).
Clear progress can be made each week, and the community could be
involved
in choosing feature priority.
- Now that PDF::Reader exists, automated testing is actually
possible. The
project may also help push PDF::Reader along, potentially resulting
in some
shared code, or other kinds of collaboration
CONS:
- I'm not well acquainted with the PDF spec, I'll need time to read
it
- I'm not well versed in m17n, I'll need to spend some time learning
- PDF::Writer already works (sort of)
- A special case project (Not everyone works with PDF)
- Project may take less than 22 weeks for the juicy parts.
(Though I'm not sure)
- May take several weeks to get to an experimentally useful state.
=== Uncovering Hidding Ruby Gems (Documentation)
The goal of this project would be to produce a broad range of tutorial
articles about various useful Ruby packages and tools. The community
would help
me select projects that are interesting, and I would produce 1-2
articles a week
which would be released under a free documentation license.
The goal of these documents would be to give readers working knowledge
of some
notoriously under-documented libraries, using as many practical
examples as
possible, so that the documents would also serve as a sort of quick
reference
whenever possible.
With sufficient community interest, I could produce a typeset book for
print at
cost, through Lulu. I already have some experience with this via the
Ruport
book, so it is definitely a possibility if people like the idea.
PROS:
- Ruby is *still* lacking quality documentation, so this definitely
will help
fill some holes.
- 22 weeks is a very large chunk of time, so a lot of work could be
done on
this.
- Many projects in Ruby are relatively unknown because of their lack
of
accessible documentation, not because of their lack of quality. A
large
documentation drive would hopefully spark a lot of new developments.
- I have a decent amount of technical writing experience.
- It may be possible to produce a very inexpensive print book at cost
which
offers a cornucopia of Ruby tutorials
CONS:
- Difficult to figure out which topics are most important
- Lots of context switching, which may be a bit inefficient
- I'm a little afraid of burning out if I'm producing 1-2 articles a
week
- This project idea has had mixed responses from the community, many
like it,
but more than a few claim it lacks focus.
- Topics will have to be things that I can either learn quickly or
already have
some experience with, to ensure the documentation is of some
quality.
- We still don't have a large list of specific projects that deserve
attention,
much less community consensus on which are most important.
As requested I've put together a sort of analysis of the PDF project
vs. the documentation project.
The way it looks now is that a PDF::Writer rewrite is the project to
beat. Though some have mentioned they don't personally have a use for
it, most of them agree it is a worthwhile project and would be willing
to support it. Many have indicated this project seems like the most
likely to succeed among my ideas. Given that the task would be to
implement a software library based on a well defined specification,
and the fact that we already have a sense of what some of the
challenges involved with this are, I tend to agree.
However, I still think the documentation project has a lot of merit.
If in the next couple days, it seemed like we got together a clear
plan for the kinds of topics we'd be covering and how the project
would progress, it remains to be a possibility. I definitely am
holding some reservations about this though, because very few people
have come up with concrete ideas about this project, and that makes me
nervous.
Below, you'll see my current thoughts about the pros and cons of each
project. Please feel free to speak up and let me know what you are
thinking. Essentially, if we can't get together at least the
beginnings of a clear plan for the documentation project by April 2nd
or so, I think I'll go with the PDF project. However, if we can get
the doc project ideas organized and I can get a sense of the
community's support for it, it still has a chance.
So... silence gets you PDF, some well thought out cajoling might get
you many months of documentation work. :)
Analysis of the projects follows.
-greg
###########################
=== First Class PDF Support in Ruby
The goal of this project would be to write a tiny, fast, and beautiful
PDF writing library for Ruby. This project would support Ruby 1.9 and
m17n from
the ground up, eliminating two serious issues for those currently
generating
PDFs in Ruby.
Ideally, this project could replace PDF::Writer in the near future.
PROS:
- This is a complicated project that is unlikely to get worked on in
people's
spare time, which means it is somewhat ideal for Ruby Mendicant.
- As one of PDF::Writer's principal maintainer's, learning more about
will be helpful immediately to me, and PDF::Writer's users.
- Ruby 1.9 deserves third party library support
- A new PDF writing package would open up a lot of possibilities for
Ruby
Reports (Ruport), as well as simplify porting Ruport to Ruby 1.9
- Currently the most popular project idea for Ruby Mendicant
- Forms a complete, extremely well defined project (due to the PDF
spec).
Clear progress can be made each week, and the community could be
involved
in choosing feature priority.
- Now that PDF::Reader exists, automated testing is actually
possible. The
project may also help push PDF::Reader along, potentially resulting
in some
shared code, or other kinds of collaboration
CONS:
- I'm not well acquainted with the PDF spec, I'll need time to read
it
- I'm not well versed in m17n, I'll need to spend some time learning
- PDF::Writer already works (sort of)
- A special case project (Not everyone works with PDF)
- Project may take less than 22 weeks for the juicy parts.
(Though I'm not sure)
- May take several weeks to get to an experimentally useful state.
=== Uncovering Hidding Ruby Gems (Documentation)
The goal of this project would be to produce a broad range of tutorial
articles about various useful Ruby packages and tools. The community
would help
me select projects that are interesting, and I would produce 1-2
articles a week
which would be released under a free documentation license.
The goal of these documents would be to give readers working knowledge
of some
notoriously under-documented libraries, using as many practical
examples as
possible, so that the documents would also serve as a sort of quick
reference
whenever possible.
With sufficient community interest, I could produce a typeset book for
print at
cost, through Lulu. I already have some experience with this via the
Ruport
book, so it is definitely a possibility if people like the idea.
PROS:
- Ruby is *still* lacking quality documentation, so this definitely
will help
fill some holes.
- 22 weeks is a very large chunk of time, so a lot of work could be
done on
this.
- Many projects in Ruby are relatively unknown because of their lack
of
accessible documentation, not because of their lack of quality. A
large
documentation drive would hopefully spark a lot of new developments.
- I have a decent amount of technical writing experience.
- It may be possible to produce a very inexpensive print book at cost
which
offers a cornucopia of Ruby tutorials
CONS:
- Difficult to figure out which topics are most important
- Lots of context switching, which may be a bit inefficient
- I'm a little afraid of burning out if I'm producing 1-2 articles a
week
- This project idea has had mixed responses from the community, many
like it,
but more than a few claim it lacks focus.
- Topics will have to be things that I can either learn quickly or
already have
some experience with, to ensure the documentation is of some
quality.
- We still don't have a large list of specific projects that deserve
attention,
much less community consensus on which are most important.
Trans
Mar 30, 2008, 11:46:00 PM3/30/08
to RubyMendicant
On Mar 30, 10:20 pm, Gregory Brown <gregory.t.br...@gmail.com> wrote:
> - I'm a little afraid of burning out if I'm producing 1-2 articles a
> week
you, but I get a little stir crazy if I work on only one project for
22 weeks straight ;-) If you could do a docs article every 2 weeks,
that would still be 11 articles and give you some diversion from the
PDF::Writer.
Just a thought,
T.
Gregory Brown
Mar 31, 2008, 9:07:29 AM3/31/08
to rubyme...@googlegroups.com
This isn't an option, really. I will likely need to pick up work
again immediately after this period of time, so stretching out the
project would sort of defeat the purpose of raising money to spend
dedicated time on the project. :)
Also, I don't want to take on two projects simultaniously. If I get
the PDF library to a workable state before the time period is up, I'd
be happy to kick out a few articles about various topics at the end of
the period, but I definitely don't want to switch back and forth.
-greg
Trans
Mar 31, 2008, 12:10:04 PM3/31/08
to RubyMendicant
On Mar 31, 9:07 am, "Gregory Brown" <gregory.t.br...@gmail.com> wrote:
>
> This isn't an option, really. I will likely need to pick up work
> again immediately after this period of time, so stretching out the
> project would sort of defeat the purpose of raising money to spend
> dedicated time on the project. :)
>
> Also, I don't want to take on two projects simultaniously. If I get
> the PDF library to a workable state before the time period is up, I'd
> be happy to kick out a few articles about various topics at the end of
> the period, but I definitely don't want to switch back and forth.
T.
Nathan
Apr 3, 2008, 12:08:01 AM4/3/08
to RubyMendicant
Gregory,
If you do PDF::Writer, I would hope that it would be an exception to
the under-documented Ruby gems, and come with good docs (i.e. like
Ruport). Set the standard.
Back in the day I spent some time with reportlab to generate PDFs, and
was quite impressed with the simplicity and capability (such as word-
wrapping within a bounding area). Among reading PDF specs, it might be
worth a look as you prep for the project (yah, it's Python).
http://www.reportlab.org/
- nathan
Gregory Brown
Apr 3, 2008, 12:10:31 AM4/3/08
to rubyme...@googlegroups.com
On Thu, Apr 3, 2008 at 12:08 AM, Nathan <nyou...@gmail.com> wrote:
>
>
> Gregory,
>
> If you do PDF::Writer, I would hope that it would be an exception to
> the under-documented Ruby gems, and come with good docs (i.e. like
> Ruport). Set the standard.
>
>
> Gregory,
>
> If you do PDF::Writer, I would hope that it would be an exception to
> the under-documented Ruby gems, and come with good docs (i.e. like
> Ruport). Set the standard.
I've selected the PDF project as what I'll be working on (as a new
implementation known for now as Prawn, rather than refactoring
PDF::Writer). I plan to document it well, but be sure to bug me if
that doesn't seem to be happening a couple months from now.
-greg
Reply all
Reply to author
Forward
0 new messages