Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:43016
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain lsces.co.uk from 213.123.26.185 cause and error)
Message-ID: <4993E03F.6060909@lsces.co.uk>
Date: Thu, 12 Feb 2009 08:39:27 +0000
User-Agent: Mozilla/5.0 (X11; U; Linux x86_64; en-GB; rv:1.8.1.19) Gecko/20081216 SeaMonkey/1.1.14
MIME-Version: 1.0
To: PHP internals <internals@lists.php.net>
References: <53C9D049-8C10-48F2-8312-C8A81D2B5990@pooteeweet.org> <00a601c98c7b$4ed5a4a0$919f644d@foxbox> <7f3ed2c30902111113q364b4094q22c71c1046a984a6@mail.gmail.com> <00c301c98c7d$da9cce80$919f644d@foxbox> <00d401c98c7e$a92bfcd0$919f644d@foxbox> <261daaa10902111131u61ad7ec9s9257a45e1e11f086@mail.gmail.com> <00ec01c98c81$2696b2d0$919f644d@foxbox> <fe05d1540902111146n729261a9l2386ae49aa781f1d@mail.gmail.com> <00f501c98c82$b8c560b0$919f644d@foxbox> <7f3ed2c30902111420n56ecd4cbl5f95b2e2e511de6@mail.gmail.com> <6836D93C-CB43-4E15-9ABA-C479FBCCA035@pooteeweet.org>
In-Reply-To: <6836D93C-CB43-4E15-9ABA-C479FBCCA035@pooteeweet.org>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DEV] 5.3 todos
From: lester@lsces.co.uk (Lester Caine)

Lukas Kahwe Smith wrote:
> Hey Steph,
> 
> Personally I think we should list all changes. For certain changes we 
> should devote some explanations (like E_DEPRECATED). For the most part I 
> see this document as a place where we provide an overview of things 
> which then gives them the right key word to look in the documentation. 
> Also like in the case of E_DEPRECATED we should briefly explain the 
> reasoning and how people should adapt their php.ini files .. so in that 
> sense all longer text should be about migration issues, where are 
> documentation is more about documenting the behavior in each version.
> 
> I expect some people to skim this document, others to read it to the 
> letter, others will just grep it if they run into issues. Thinking about 
> it, we should somehow try and make sure that any likely error message 
> that people will see in their error logs after upgrading will get them a 
> hit when they search for it in this document.
> 
> So in summary, I feel the key point for this document is:
> - a single document that lists all changes
> - contains pointers that enables someone to look up more details in the 
> documentation
> - enables people who get new "strange" error messages to find pointers 
> towards the documentation
> - some lengthier migration related explanations that go beyond what we 
> want to provide in the documentation

That sounds about right ...
BUT perhaps some of the more complex explanations should have their own 
document. If it 'requires more explanation than we want to provide in 
the documentation' that does seem to suggest that a development perhaps 
DOES need better doumentation?

-- 
Lester Caine - G8HFL
-----------------------------
Contact - http://lsces.co.uk/lsces/wiki/?page=contact
L.S.Caine Electronic Services - http://lsces.co.uk
EnquirySolve - http://enquirysolve.com/
Model Engineers Digital Workshop - http://medw.co.uk//
Firebird - http://www.firebirdsql.org/index.php