[reportlab-users] Bulleted Text not displaying

[Dinu Gherman]

Preface: This should probably be under a different subject
line, but I'm adopting here the usual behaviour to ignore
such little details.

Andy Robinson:


> Dinu Gherman <gherman at darwin.in-berlin.de>:

>> Very well explained! Wikis have been suggested repeatedly

>> starting as long as eight years ago, maybe.

>

> Dinu, you forget that we set one up, and NOBODY except you

> used it. I think you added a few headings for others to fill in.

> Then we had to take

> it down when it got abused; it wasn't worth having an employee

> check it every few hours for abuse, or tighten up the security, when

> it was getting zero real use.


Maybe it's me who has some false memories here, but I don't
remeber that the Wiki you mention (I think it was MoinMoin)
was public and even less that it was abused. I do remember
though that nobody else inside ReportLab used it, yes, be-
cause it didn't fit into its culture and belief system (my
post-mortem analysis).


> Also,

> each time you raised this on lists over several years, I said

> "OK, who's going to contribute some documentation?" and

> got no volunteers.


Is that another incarnation of the chicken-egg issue? Well,
without some decent machinary you won't get any eggs. And
just repeating that question didn't seem to help up to now,
then, did it?


> If you are referring to deciding to keep our docs versioned along  

> with our

> source rather than in a Wiki or FLOSSManuals, well, that's an

> engineering decision

> primarily stemming from the fact that our self-generating manuals are

> the biggest

> functional test cases we have; and because we think we can make them

> into very good tutorials on "how to publish a nice manual" over  

> time, which

> is of wide interest.


Then we probably just arent't there, yet? It's interesting
to imagine a fictional startup named RebortLap trying to get
funding from venture capitalists by saying "we'll publish
a really cool manual to our product in ten years time." Yes,
I'm exaggerating - sometimes a good technique to get insight,
though.

Engineering decision... are you really promoting your method
of tutorial creation? Has anybody in real life outside of
ReportLab adopted it for creating tutorials? I'd be surprised
if that happened. I'm writing quite a lot of text with many
different systems, but none of them looks like programming
(not even LaTeX). Why? Because writers want to write.

I think you're mixing different things, first the RL documen-
tation and its role for the community and second your commer-
cial projects and the features you need there.

The most important purpose of the first is to learn how to use
the library while reading the document, not the code needed
to generate it. And if you want people to contribute you have
to make that easy. Asking programming skills and complicating
the process is not going to make contributions easier to make
in a world of WikiPedia and similar sites.

Showing the formidable skills of ReportLab stuff and code in
generating all documents needed in the financial or other in-
dustries is a different issue, because here you address de-
cision makers. This can be done with sample documents and
code taken from a "hall of fame of successful ReportLab pro-
jects". And I'm sure you're doing that. But it has nothing
to do with the real purpose of the manual (documentation).

Since this posting is getting too long (sorry for repeating
too many obvious things) and I have more important stuff to
do, I'm closing with an idea you get for free: If you really
want to be open and closed at the same time, why don't you
set up a subsite where people can edit the manual code in
RML which would be rendered on your site into PDF and could
also be downloaded by others and rendered offline using
z3c.rml?

That could be a nice warm-up project for your new staff and
would, perhaps, allow to keep together the various different
purposes for the manual (documentation, test and gallery),
all under your centralised control. That would mean a depar-
ture from letting people easily render the documentation
themselves, but I think most want to just read it, anyway.

Regards,

Dinu

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://two.pairlist.net/pipermail/reportlab-users/attachments/20081022/066f6acc/attachment.htm>