Re: Create/update Internals section

Hi, On Tue, Apr 10, 2018 at 10:33 AM, Rowan Collins <rowan.collins@gmail.com> wrote: > 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 use the Internals Book as an example because it is the only reference I could remember. And that's why I suggest that we should have our own internals reference, on the PHP Doc. I can, of course, create an internals documentation in other place, although I'm not sure I would contribute on the Internals Book because of the different licence permissions between PHP Doc and the Internals Book. To me the question is, why we can not have a reference (even if is a simple one) of the internals on the PHP Doc itself? Because it's hard to maintain? Because there's the IB, even if it is also outdated or incomplete? >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? > By use as a base I mean to get the overall picture of the contents and what kind of content we should have, to use for planning, not copy and paste. >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. > I'm working in other documentations, but only for a while, so maybe I don't have too much experience to affirm this, but I think that this is intrinsic to the nature of the docs, the more (good) content you have, the harder will be to maintain, as the language itself is always evolving, but the easier will be for others to read it and find the answers they need. 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. > When I thought about update this section, I thought about having an updated reference for the internals, on the official docs, even if it is a simple one. And, of course, add more content with the time, after have the initial version in place and see what's missing that can be added. But if the majority of you think it is (or will be) a waste of work, or that it makes no sense to have this content (or the most of it) on the docs, feel free to keep on with the previous plan. I still disagree, but I can live with that. Best Regards, *Adiel Cristo* Senior PHP Developer adielcristo@gmail.com LinkedIn <http://br.linkedin.com/in/adielcristo> | DevBlog <http://www.adielcristo.com/blog/pt>