| Re: Major trouble with PhpDocumentor [message #182330 is a reply to message #182325] |
Sun, 28 July 2013 16:38   |
Fiver
Messages: 35
Registered: July 2013
Karma:
|
Member |
|
|
On 2013-07-28 16:36, Scott Johnson wrote:
> Wow fiver.
>
> Jerry simply gave you a reference of where you 'might' find better
> advice and you fight him at every turn to the point of being sarcastic.
>
> He never said you where stupid or would not find help here, just gave
> you a suggestion.
>
> Makes me think now if anyone had advice on how to fix your issue you
> might fight them as well.
Yes, that last message did turn out more aggressive than I had intended.
My apologies to Jerry; it had been a very long and frustrating day. In
my defense, I did not need to be told how to contact the PhpDocumentor
developers; I already knew that. I've also spent over an hour digging
through their bug tracker.
What annoyed me was being lectured on how to properly design a project.
I don't agree that having the API documentation separate from the source
is a good idea, and I'm certainly not alone in that opinion. I also have
my reservations about the claim that large software projects can be
designed perfectly from the start and will never deviate from the
original plan, even when you exclude client requests. Such a claim
stands against everything ever written about software development and
project management - including The Mythical Man-Month - and also against
my 20+ years of experience in the field. In any non-trivial project
(months to years), the original design will evolve; external tools will
be updated or exchanged; unexpected problems will be discovered;
previously unknown data errors will have to be worked around; APIs will
drift and expand; hardware will change; newly discovered security
threats will have to be avoided; new techniques will become available;
new developers will enter and bring their knowlege into the project;
etc. If it was feasible to anticipate all those factors from the outset,
the job of a project manager would be reduced to that of an overseer.
Methods like agile development wouldn't exist, and hundreds of book
authors would be out of a job. I don't know, maybe Jerry is the
exception to the rule. For everybody else, though, it's a good idea to
expect changes and deviations during the course of a project. The
development workflow should reflect that, and having the API
documentation close to the source is just one of the tools used to
accomplish that.
regards,
5er
|
|
|
|
Calendar
Search
Help
Members
Register
Login
Home
]