On 06/13/2014 10:26 PM, Barrie Treloar wrote:
On 14 June 2014 02:14, Robert Kuropkat <[email protected]> wrote:
<snip>
I'll add my cry of despair here as well. Modern Open Source documentation
efforts tend be mostly disappointing. First of all, it's never in a nice
neat collection. Second, most of the articles and examples supplied by
Senior Mentor Google are stale, trivial and sparsely explained.
Explanations are rarely more than a statement of the obvious (Property:
enabled: true/false - enable or disable feature). The question of WHY is
rarely addressed and downstream results never. Even if you do find a well
detailed example it is very specific (cookbook style) with little
explanation of the options NOT chosen and why.
I'm running into this right now in fact. I did some proof of concept
testing on a bunch of plugins for my group, things looked good and now I'm
reviewing my configurations and documenting them. I've managed to run
across a few issues where configurations I plucked off the Internet are
"working" but don't seem to be valid. At least I can not find any
documentation for the options I set. Is it stale documentation?
Deprecated options? Just plain wrong examples? With a configuration file
like XML which is designed to ignore options it doesn't understand, this is
even more frustrating. With rapidly changing feature sets it's maddening.
Sometimes the people implementing things can't see things from a fresh
perspective - they can't unlearn what they already know.
That is why we rely on the community to provide patches - even to
documentation - to help clarify things.
It's a great place to start if you want to get involved - it's where I
started.
We also need people withe skills and desire to improve documentation.
Technical writing and cutting code are orthogonal skills that rarely sit in
one individual.
So if you have someone on your team who can write technical docs then
convince them, your management, etc that it benefits your team to help
improve these docs and give back to the project. It will also help future
projects at your org.
Definitely understand the issues, just wish I wasn't short on answers or
suggestions. I usually try not to spend much time complaining when I
have nothing useful to offer up...
As you said, the skills don't usually align. My own documentation
efforts are more desperation attempts to not be bothered by things I'm
no longer working on. I mentioned in a reply off list some of what I am
doing now might be possible to offer up, though I'm afraid it will
likely at least start in one of the same categories I mentioned above of
being overly specific. However, it may serve as a useful starting
point, so I'll see what I can do.
Thank you for the answers below. That reporting section thing was
driving me nuts. Now if I can just figure out why setting
altReleaseDeploymentRepository and altSnapshotDeploymentRepository in
the settings.xml file don't seem to actually do anything, requiring you
to use altDeploymentRepository property instead....
<snip>
Robert Kuropkat
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
