| Re: Major trouble with PhpDocumentor [message #182337 is a reply to message #182330] |
Sun, 28 July 2013 19:01   |
Jerry Stuckle
Messages: 2598
Registered: September 2010
Karma:
|
Senior Member |
|
|
On 7/28/2013 12:38 PM, Fiver wrote:
> 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
>
Maybe you don't agree - but I've been doing it for over 40 years, and in
that time I've worked on some very large projects - multiple
programmers, even several designers working together.
Changes in external tools and hardware are some of the client
requirement changes I talk about. Proper design and testing will
eliminate all security threats (and many - but not all - other bugs).
And new developers can bring additional knowledge to the task, but if
the original developers are experienced and knowledgeable, the design
will not change.
As for documentation being independent of source code - this is critical
for good QA. Testing is done to the DESIGN - not to the CODE. Ideally,
testers won't even have the source for the code being tested (I know
that's not really possible in PHP). Otherwise, the tester is going to
write tests based on the code that exists, not what it's supposed to do.
A lot of bugs are missed this way.
My job as a project manager is much more than just overseeing things.
It includes following the project's progress, keeping in touch with the
client, making changes in the documentation as necessary and ensuring
those changes are communicated to the developers; monitoring the
timeline and continually estimating project costs and projected
completion date - a lot of work.
Oh, and BTW - the documentation system we use is based on SQL databases.
One of the things in the database is a "Calls" column. When we are
designing method "a" and it calls method "b", method "b" is
automatically updated with the fact that "a" is calling it. That way if
we do have to change the interface, we know *exactly* which methods need
to be addressed (and tested again). You can't do that in source code
comments, either.
I always expect change and deviation in a project. That's why keeping
the documentation separate from the code is so important.
--
==================
Remove the "x" from my email address
Jerry Stuckle
JDS Computer Training Corp.
jstucklex(at)attglobal(dot)net
==================
|
|
|
|
Calendar
Search
Help
Members
Register
Login
Home
]