Hello Dirk,
To make it short: you did everything correctly and *normally* you should
have received an answer to your first mail ("2 Trac Questions"). I even
wanted to reply myself, but probably got caught in some other
distractions... must have been the same for the others. A gentle "ping"
follow-up would have probably worked.
But as we're at it... let's see what we can improve.
On 9/23/2010 5:08 PM, Dirk Stöcker wrote:
Hello,
Trac has a serious documentation problem. Normally I have 3 types of
help when developing software:
* documentation of the API
* examples
* help by users or developers
Now for Trac I have the problem, that all 3 types fail.
- 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...
- 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.
- 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 that documentation is always complicated problem, but if NO way
to get information really works, then the concept is flawed.
I suggest two things:
1) Make the examples in code which surely exist available at the website
in the way of a "suggested reading". Give me the possibility to
actually find source code examples. For JOSM, the largest project I
manage, you can actually enter parts of the code and most Google links
lead you to relevant pages and source code (and we also have very
little real written documentation).
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).
2) Answer questions in the development group at least with a "read this".
Sure.
+ 3) make api-doc
I'll start working on that soon (http://trac.edgewall.org/ticket/8695).
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.
Of course, ideally we should have a larger "us", and that's really only
a 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!
-- 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.
