On 9/23/2010 7:09 PM, Dirk Stöcker wrote:
On Thu, 23 Sep 2010, Christian Boos wrote:
- The online help on the Trac pages is mainly not existing.
I suppose you have seen the TracDev/ pages. Those pages could be
always be improved and refreshed, but it's not fair to say that the
online help is non existing...
Well, yes I have seen these. But the problem there is, that these
pages end, where the problems start. I'm a pretty experienced
programmer and able to find out a lot myself. The docs contain all the
information I was also able to find out by reading code, whereas
everthing which I did not find out is missing there as well.
Ok, but then give us some specifics about what you'd expect?
I did not say this is useless, for beginners it may be a start, but I
fear beginners will much earlier than I find big walls stopping their
progress.
For me time is the most limiting factor. If I don't find information
in a proper time span, I stop there and do something else. I have
enough to do, having about 600 tracker entries in JOSM alone.
- The examples may exist, but can't be found. Whenever I try Google to
find something related to Trac searching for API names or
functions I
find lots of patches and bug reports, but never found anything
helpful.
Well, trac-hacks is one source of inspiration, though not all plugins
are examples to follow...
The best examples are still in the Trac source code itself, you
should have a copy at hand and "grep" in it.
That may be an idea, yes. But if I would have a complete copy of every
project I work for, then I would need much larger harddisks. Google
has to find the SVN. Currently it seems not to find it as it should.
You should investigate why (or why not prominently - I usually do not
read Google pages 3-xxx). SVN and SVN revisions are very helpful when
found in Google. Google has a nice feature called the webmaster tools
which helps to analyze external links, internal links, relevance,
click rate, search terms and so on. For another site (BTW a Trac
instance) we did some work to get SVN found in Google including proper
redirects for documentation in SVN and so on. Result have been much
improved ratings in Google.
I wasn't clear in my first answer: we currently *block* access to these
via robots.txt, as we used to have server load issues. The suggestion I
made was to unblock (selective) parts (and let google do its magic).
- Asking questions on Trac-Devel seems to have no effect at all, as my
mail posted one week ago got not one reply.
Well, just bad luck, usually those questions *do* get answered, and
if not, just be patient or insistent... Some people prefer to use the
#trac channel on IRC for quick Q&A sessions (osimons is usually there
and willing to help).
I know mail gets overlooked. For JOSM I answer every mail after at
least 4 days when no other developer answered. Ignoring is not nice.
Ok, we could allow spidering on tags/trac-0.11, tags/trac-0.12, maybe
even on trunk though its a moving target, but we would need to fix
http://trac.edgewall.org/ticket/5177 first. And hope that t.e.o could
take the load ... (I think it should given the improvements we made
to the infrastructure).
The webspiders are gentle nowadays, so I would not care. If load is
really a problem later, then I think a solution could be found for
this as well. Finding a server for really good projects is no longer a
problem today.
+ 3) make api-doc
I'll start working on that soon (http://trac.edgewall.org/ticket/8695).
I did not suggest this, because this takes usually A LOT OF TIME and I
refuse to do so for JOSM myself. It is welcome to have a good doc, but
I do not expect it. After a while every developer learns to live with
examples and source and only slight documentation hints.
Well, if a reference documentation is not what you were looking for, I'm
at loss of what exactly you're looking for. Example usage? We have a few
in the sample-plugins/, we could possibly integrate more of them, yes.
Since I first had contact to Trac development I have the
impression, that
you actually don't want to have external developers (the admins
know about
the trouble we had until I took over SpamFilter plugin). I can't
understand this, as Trac is really a good product.
Well, that's not true, we keep trying to improve this. For example we
put a lot of efforts in the last months for setting up an
infrastructure allowing easy cloning of the Trac repository (via hg
or git, http://trac.edgewall.org/ticket/9235), and this should make
it easier for people to contribute changes and for us to review
contributions.
I can only state my opninion. I would find it nice, when you prove me
wrong in the future.
I hope so ;-)
Of course, ideally we should have a larger "us", and that's really
only a
You can't influence that really. Giving newcomers a bit more attention
surely helps. I'm in OpenSource business more than 20 years and got a
thick skin in this time, so I care for some parts of Trac even if I
was discouraged. But I fear this is not true for many others. I lost
members of development teams because of much less important reasons.
matter of someone being serious enough about investing time and
energy into the project. But even smaller contributions already help
us a lot, be it for ticket triaging, or the occasional fix or new
feature, or even... documentation improvements!
Don't count on others improving the documentation. It wont happen.
Well, Trac is for part a wiki, and the documentation lives and is
maintained via the wiki. I know some people here are dismissing this way
to build the documentation, but fact is that most of the TracGuide got
written and is maintained this way, and we had lots of people paying
attention to it, contributing big and small changes, reviewing... it
sort of works, and certainly better than people sending us documentation
patches (*that* never happened).
If the TracDev/ part is too "light-weight" for your taste, suggest us
some more involved topics... maybe you should point me to some JOSM (or
other) docs which do something similar to what you'd expect us to
provide. Something in between overviews and guidelines given in TracDev/
and an API reference? Wouldn't the API reference (with short in-lined
examples) be the best solution for people like you?
For JOSM people constantly request better online docs and always tell
me what support is missing for them to do it themselves. Over the time
I implemented lots of stuff, but the persons always vanished without
writing a single word (and here I talk about much easier end-user
docs). Sometimes there are people writting docs, but it is very seldom
:-)
P.S. By sending a mail like this I hope to improve the situation. If I
would think it is hopeless, then I would simply ignore the whole stuff.
It's appreciated, thanks!
-- Christian
--
You received this message because you are subscribed to the Google Groups "Trac
Development" group.
To post to this group, send email to trac-...@googlegroups.com.
To unsubscribe from this group, send email to
trac-dev+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/trac-dev?hl=en.
