Re: Create/update Internals section

On 10 April 2018 13:17:07 BST, Adiel Cristo <adielcristo@gmail.com> wrote: >Hi Rowan, > >Thanks for the suggestions. > >I think that (in the long run) this section should give the bases so >that >the developer, >at the least, understand what's going on under the hood. > >Other point, I intend to document the preferred ways of doing things, >using >the >e-mails already on the internals list, and any help that I can find. This is quite a broad scope, and I'm still not really clear *why* we need this. Is the aim simply "like the Internals Book, but on php.net"? >I'll >use the >Internals Book [1] as a base for the first drafts and from there we can >adjust the things. Adjust it how? What are the editorial aims that are different between the two sets of documentation? What changes do you expect to make as you import the content that couldn't be contributed to the Internals Book as improvements? >I know it is a really tough job, and that it will not be accomplished >in >just a few days. >Quite the opposite, it will be an ongoing effort, but it's needs to be >done, and once >the first version is in place, things will be easier. My main concern is that this is not necessarily the case. In my experience, keeping documentation up to date is one of the hardest parts of it, and out of date documentation can become worse than nothing, as you waste time trying to do things the wrong way. The more content you add, the more you have to maintain, and by the time you've documented everything, parts you wrote first may already be out of date. And if you replicate everything that's in the Internals Book, worded slightly differently, there will be twice the effort needed as a community, to keep both up to date. That's why I think this section of the manual should either just link to the Internals Book (as others proposed), or have a much more narrowly defined purpose (and link for more depth). If the content is concise enough, you might even get translators on board, giving a concrete benefit to having this on php.net; if it's not, I honestly don't understand the point. Regards, -- Rowan Collins [IMSoP]