3

I've noticed people have moved on with documenting PHP 7.1 even though it's just moved on to Beta 1 (at current it will be out probably in Sept). PHP uses a RFC system to approve new features, so things approved for release will make it out (more or less) in the way the RFC describes.

I ask because this is in the version editor (emphasis mine)

Only list versions that see significant real world use. Pre-releases, release candidates, alpha/beta versions, and so on only serve to clutter the topics they're applied to.

That's fine and good, but the problem is that trying to add a version specific wrapper to Examples of these new features fails because it's not defined as a version in Docs yet. Furthermore, people are already discussing and documenting these new features. Removing them (when they would have to be re-added) seems counterproductive.

Provided that the language has a standard way of approving new features for release, can using Docs this way be acceptable?

7
  • 1
    Documentation is meant to be stable. So, having unstable stuff being documented is just ridiculous. We aren't even sure we would edit them tomorrow or the day after.
    – Braiam
    Jul 27, 2016 at 13:17
  • 2
    ...So define it as a version? I mean, if you want to do this. I don't really see the motivation. It's not like we are running out of released software to document. Jul 27, 2016 at 13:55
  • @CodyGray but that's not the fastest gun way of thinking
    – charlietfl
    Jul 27, 2016 at 13:57
  • @CodyGray The main thing here is you can't version wrapper any version not defined for the tag. So if it's for a pending release you can't treat it like any other versioned Examples
    – Machavity Mod
    Jul 27, 2016 at 14:00
  • At the moment, there are still plenty of ways for the gunslingers to shoot themselves in the foot, @charlie. Machavity, I don't really understand what you mean. In my experience/understanding, the "version" table is just something else that can be edited. So you can just add beta versions to the table if you want. Is there something different about the PHP tag, where they're pulling the contents of that table from PHP version-specific tags that already exist on SO? Jul 27, 2016 at 14:10
  • @CodyGray I'm talking about version tagging like <!-- if version [gte 5.6] --> See stackoverflow.com/documentation/php/504/classes-and-objects/…
    – Machavity Mod
    Jul 27, 2016 at 14:18
  • Right. Which, as far as I understand, pulls from this table. So you could just add 7.1 (Beta 1) to that table. Jul 27, 2016 at 14:31

1 Answer 1

0

I don't see the issue with SO Documentation including beta products. Every beta product I have ever used had at least some documentation. So what if it changes? That is the risk of using a beta product. Even stable products can have documentation that changes frequently.

Perhaps a beta flag and/or a prominent note about what beta means could be added to the documentation page?

Not the answer you're looking for? Browse other questions tagged .