On Thu, 23 Sep 2010, Christian Boos wrote:
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?
For example I found a doc explaining how to switch from old to new
template system and a very tiny example. But there is nothing to explain
how it actually works. No links to the docs of the template system itself,
no links to example code of different types, ...
So I fail for the simple task of adding new links to a page. This is
probably easy and I also can find a way which is hacky, but I do not find
a correct way to do it.
Here help would be links to example code and corresponding template file,
so one can actually see how it works together.
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).
So there is a load problem? Does Trac site have such high requirements or
is it running on a very small hardware?
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.
Well, proper docs would be fine, but I don't expect them. I can help
myself when I find something I can work with. But for Trac even these
required hints and tips are missing or hard to find. So for me a first
step would be to get such hints available. Long time developers usually
have a broad knowledge and can answer most questions with "Read that part
of doc/code". You know which parts of code are good and which aren't
so nice. Make this available to beginners as well.
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).
JOSM doc is also a WIKI :-) Doesn't really help a lot. Well, ok, WIKI
based documentation is changed by others, but compared to the amount of
work really needed to be done this is nearly nothing.
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?
Sure it would. But as said, this means a lot of work and this also means
this work cannot be spend in improving the software itself.
Ciao
--
http://www.dstoecker.eu/ (PGP key available)
--
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.
