Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:125338
Message-ID: <ccb45cdf3969e959bf6750483c127f35727f36ac.camel@ageofdream.com>
Subject: Re: [PHP-DEV] [RFC] [Discussion] Using and Mentioning Third-party
 Packages in PHP Documentation and Web Projects
To: internals@lists.php.net
Date: Wed, 28 Aug 2024 10:28:23 -0400
In-Reply-To: <819bcfbb-b747-4ed1-a878-bf5a8e00935e@app.fastmail.com>
References: <663bea3c-a8e7-4881-2bcb-971a96dea9cb@php.net>
	 <6B084580-CEFA-45A3-8221-944B9502B745@getmailspring.com>
	 <819bcfbb-b747-4ed1-a878-bf5a8e00935e@app.fastmail.com>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
User-Agent: Evolution 3.46.4-2 
Precedence: bulk
MIME-Version: 1.0
From: lists@ageofdream.com (Nick Lockheart)

>=20
> What a couple of people have touched on is that that all we have
> right now is a Reference, which is only one kind of documentation.=C2=A0
> The common zeitgeist these days says there's 4: https://diataxis.fr/
>=20
> * Tutorials
> * How-to guides
> * Explanation
> * Reference
>=20
> We have a reference with gaps, and that's about it.=C2=A0 In practice, it
> will be functionally impossible to write a meaningful tutorial or
> how-to guide that never mentions anything but php-src-provided code.=C2=
=A0
> Or at least the result would be sub-standard and doing the reader a
> disservice.
>=20
> I don't think I'd support a list of "popular" frameworks, but
> mentioning Composer, Xdebug, and PHPUnit seems a requirement for a
> useful modern tutorial.
>=20
> Admittedly, the docs team is very under-resourced right now and even
> the reference section has not-small holes, making maintaining even
> more types of documentation a potential challenge.=C2=A0 That's something
> the Foundation could possibly help with.=C2=A0 But that's not the topic a=
t
> hand: The topic at hand is just "look, we should be able to mention
> Composer, Xdebug, and PHPUnit, OK?"=C2=A0 On which I very much am in
> agreement.
>=20

Since we are talking about 3rd party tools, is "documentation" not a
tool?=20

Could we have a section for "further learning" that links to books and
websites?