Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.php > #10288

Re: Major trouble with PhpDocumentor

Show key headers only | View raw

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@attglobal.net
==================

Back to comp.lang.php | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

Major trouble with PhpDocumentor Fiver <numeralfive@gmail.com> - 2013-07-28 03:25 +0200
  Re: Major trouble with PhpDocumentor Jerry Stuckle <jstucklex@attglobal.net> - 2013-07-27 21:38 -0400
    Re: Major trouble with PhpDocumentor Fiver <numeralfive@gmail.com> - 2013-07-28 04:14 +0200
      Re: Major trouble with PhpDocumentor Jerry Stuckle <jstucklex@attglobal.net> - 2013-07-27 22:22 -0400
        Re: Major trouble with PhpDocumentor Fiver <numeralfive@gmail.com> - 2013-07-28 04:45 +0200
          Re: Major trouble with PhpDocumentor Jerry Stuckle <jstucklex@attglobal.net> - 2013-07-27 22:59 -0400
            Re: Major trouble with PhpDocumentor Fiver <numeralfive@gmail.com> - 2013-07-28 06:04 +0200
              Re: Major trouble with PhpDocumentor Jerry Stuckle <jstucklex@attglobal.net> - 2013-07-28 08:05 -0400
                Re: Major trouble with PhpDocumentor Tim Streater <timstreater@greenbee.net> - 2013-07-28 13:23 +0100
                Re: Major trouble with PhpDocumentor Jerry Stuckle <jstucklex@attglobal.net> - 2013-07-28 09:37 -0400
                Re: Major trouble with PhpDocumentor Tim Streater <timstreater@greenbee.net> - 2013-07-28 15:24 +0100
              Re: Major trouble with PhpDocumentor Scott Johnson <noonehome@chalupasworld.com> - 2013-07-28 07:36 -0700
                Re: Major trouble with PhpDocumentor Fiver <numeralfive@gmail.com> - 2013-07-28 18:38 +0200
                Re: Major trouble with PhpDocumentor Jerry Stuckle <jstucklex@attglobal.net> - 2013-07-28 15:01 -0400
  Re: Major trouble with PhpDocumentor Goran <goran@nospam.com> - 2013-07-29 09:27 +0200
    Re: Major trouble with PhpDocumentor Fiver <numeralfive@gmail.com> - 2013-07-29 21:29 +0200

csiph-web