What should we do with unspecced things?

[AlexDaniel]

From this comment:

Maybe there should be a "meta-issue" to discuss where the line is drawn for un-specced items, and what the threshold for discovery of undocumented items should be.

Indeed! We need some kind of a consensus.

Also, my thoughts from this comment:

I don't like NOTSPECCED issues floating there like this (especially that amount), so I have the following idea: we should tag stuff as NOTSPECCED, but if nothing can be done now, we can close the issue. Once something is implemented, we can reopen it.
In other words: if there is nothing we can do, then we consider the issue solved at this particular moment in time. This would clear the list of open issues, and the NOTSPECCED label will make it possible to check the list periodically to make sure that nothing falls through the cracks.

[Altai-man]

Personally, I'd 👍 the second comment approach. For example, we don't have an ability to describe many pragmas because, um, they don't have a description at all, they just reserved. It'd be wise to just mark them in the docs as reserved for a future use or something like this. We need to make our issue list shorter, not longer, to be sure on what things we can focus.
About other things. I believe that we shouldn't(in the perfect world, at least) use notspecced stuff. But some things are already leaked here(correct me if I'm wrong) and we can do nothing with this.

My personal opinion is to have three levels of things(categories if you wish):

• Internal rakudo/whatever things -> we shouldn't document it.
• Internal rakudo-related things, that are useful and actually can be used outside to write close to compiler stuff, like NQP, some classes, etc(I'm bad with examples of this category). They may be documented with some warnings. It can be debated for sure, but if such things have usage in big language modules, it'd better to have them than trying to cover things under the blanket. On the other hand, it puts more maintenance burden on maintainers and we don't have them too much, to be honest.
• Official Perl 6 things -> we must document it.

[AlexDaniel]

@Altai-man is there any reason why we cannot mention these things anyway? For example:

• Internal rakudo/whatever things → document it by writing “Do not use this!”
• Internal rakudo-related things that are useful → document it by writing “Part of rakudo, but not part of the language spec. Use it on your own risk.”

What do you think?

[gfldex]

Seen from the standpoint of a language user, the spectest are rather unwieldy. The only official documentation we have for the language and therefor the spectest are the docs. As soon as we add stuff that are rakudo internals, we take responsibility for any fallout that might have. As such any such addition needs to be signed of by a language designer or we may end up painting the language into a corner via proxy.

Also, after Perl 6 has conquered the worlds, there will be many many implementations. How do you decide what implementations internals you take in and which you reject?

[AlexDaniel]

How do you decide what implementations internals you take in and which you reject?

Why reject? Let's document everything!

Imagine this: someone finds an undocumented feature and uses it in his code. Then somebody else finds this code and steals it for his own problem. That user may try to search the docs for this undocumented feature, but won't find anything. “Sure, perhaps the docs are incomplete”, right?

By knowingly ignoring unspecced features we are just making the situation worse. Look, we don't have to explain all of the details about unspecced things, we just have to mark explicitly that it is not recommended for use.

Or is there any other solution to this problem? I don't think that “you have to check every undocumented thing in roast” is something we should recommend. I can't imagine a 6-year-old doing that.

[gfldex]

Please run util/list-missing-methods.p6 and look at the sheer number of leaky methods. If we add some, we need to add all. And then remove them when they become private again.

[Altai-man]

@AlexDaniel the main reason - stable api nonsense in a compiler sense.
Yeah, you can write it with a caps lock on and some red font like "DO NOT USE THIS", but if it's mentioned, some people will use this. And then compiler folks will struggle with a backward compatibility because of us.
As a language, "we" provide just some api to user(i.e. "How to use"-rules in some sense). We use compiler stuff only in some concrete compiler - that's all. Yeah, some things are already leaked as I wrote before. but documenting all private rakudo/whatever stuff is a nonsense. Firstly, because you don't need to know how rakudo internally works to write programs. Secondly, Rakudo can be changed everyday - do you want to reflect every commit? It makes our docs a bad source, because one day it's one, but another day it's something else. We don't have good enough docs in some places for even the standard language, it'll be strange to put one another great bunch of things to do. This parts will be always outdated.
If people want to dig into compiler stuff, they have sources/compiler docs/irc/etc. But we document language, not compilers insides.
The second section is debatable(I don't have anything against documenting things that are rakudo-only, but stable and provided to a user on purpose), but the first part is totally out of question for me.

someone finds an undocumented feature and uses it in his code

If someone finds an undocumented feature or use nqp magic or something else rather obscure, it's his/her own responsibility to do so. How often when you find something awkward about insert your favorite language here you hurry up to use in in production-close code rather than ask about it? It's like 'What if someone find a gun and shoot himself in the foot, we need to document every gun with a big banner "Don't shoot yourself!"'.

[coke]

If something is runnable from user level code AND is in roast

• document it.
  Is runnable from user level code AND is NOT in roast - check with the development team:
• it might be accidentally exposed and need to be removed (And therefore not documented)
• it might need tests in roast for (and therefore needs to be documented as part of v6.c or a later version)

We should not document everything. It's not up to the docs team to decide what's in the specification, that's up to the development team. There is some overlap, but the final decision rests there.

[tbrowder]

On Friday, August 12, 2016, Will Coleda notifications@github.com wrote:
...

We should not document everything. It's not up to the docs team to decide
what's in the specification, that's up to the development team.

Is there a list of the dev team members anywhere? If not, there should be
IMHO.

[AlexDaniel]

Okay @coke, what should we do with a bunch of issues about env vars? I don't see any tests…

[coke]

@tbrowder (list of dev team members) - #perl6-dev is a good first approximation. If it's something big, might get deferred to the collective @larry (another non-explicit list of people, which at least includes Larry and Jonathan). Whatever the scope of the item, the discussion should get some kind of confirmation from the folks on IRC. Maybe add a tag for tickets that require a decision to make it easy to find.

@AlexDaniel - Regarding my recent list of tickets, excellent question - the rakudo/moar based ones can go on the rakudo wiki, and have a link to that from the spec page.

[coke]

See a5ca28f - I added basically my notes above to the STYLEGUIDE at an attempt at closing this ticket. If there are particular issues that still need to be addressed, we can re-open the ticket and enumerate them.

[AlexDaniel]

OK, according to the latest discussion (started here https://irclog.perlgeek.de/perl6/2016-12-02#i_13669580 and conclusion here https://irclog.perlgeek.de/perl6/2016-12-02#i_13669787), we decided to keep notspecced things open. The whole thing needs more clarification, so the STYLEGUIDE will definitely help, but I'll reopen this in case somebody wants to express his opinion on the issue (because the decision was kinda sudden).

[coke]

Wasn't sudden, it was "no one had anything else to say since Oct 24.".

I'll close this ticket again in a week if we don't have any more actionable feedback.

[coke]

It's been a week, and no one has commented. Re-closing ticket.