A principle/motto for the documentation

[2colours]

From what I can see, there is no simple, non-technical (or only remotely technical), broad principle or goal for the Raku documentation.

The reason I think this could be useful is that personal opinions can differ about certain aspects and topics of the documentation - there might be situations where we cannot make a consensual choice. There is only one content so it cannot equally please everyone. It would be good to have something to evaluate content and decision by. A goal we can easier agree what exact choice takes closer to.

I'm thinking of something similar to how -Ofun is kind of a motto regarding community guidelines. Perhaps it has to be more technical than that because sometimes we need to simply decide about the topics that belong to the documentation in the first place (e.g NQP opcodes probably not) - but anyway, something that is rather broadly applicable than precise.

[dontlaugh]

Here is a good philosophy about organizing docs https://documentation.divio.com/

If documentation doesn't clearly fit into one of those categories, it likely needs to be edited/refactored.

[2colours]

This makes sense - in fact, it makes too much sense to be news... The main problem is, I think, is that we are always short on resources and therefore try to minimize effort and maximize involved people. Now, people don't seem to naturally have the same attitude towards documentation. A banal example: there are people who read the documentation almost like a book. And then there's me who would 95% of the time just look up something I need to know about and read those two paragraphs and 2 function signatures that are related to that.

I doubt the big picture of this mixture will change a lot (I'm afraid). What we could be more explicit about is where different kinds of documentation can fit - what is a place to be tutorial-like, howto-like etc.

As I already hinted it, I use it mostly as a reference and I think that should be the main context - not only because that's how I would like to use it but because that's the least open topic. Tutorials and how-to's can be compiled from standalone articles, SO answers etc. which is a thing already. Explanations are more tied to the implementation and probably should find a place closer to Rakudo itself - the relation of Raku and Rakudo could be a whole other topic, both with regards to docs and the ecosystem itself.
The most persistent and reliable form of documentation should be a reference, and also, once again, this requires the most coordination and collaboration.

Anyway, even though I would appreciate to declare that "the docs" are mainly a reference, I don't think it's feasible to be this "separationist" in the current situation.

[Altai-man]

How can we extend https://github.com/Raku/doc#vision ?

[2colours]

Oh thank you... I knew about this and would have linked it if only I found it. Apparently my eyes skipped it somehow...

In the first place, I think this segment could have a bigger headline and it could be closer to the top of the page, if not right at the top.

Actually, it includes some tiny shards of explicit goals that are already pretty instructive:

• useful to every Raku programmer
• (...) resource when you want to know something about a Raku feature (...)

First off, confirm or deny but for me, this sounds a lot like a "reference" of all the things we are trying to cover. xD

Second, I'm also thinking of some "judgements" like "forgiveness > permission" or Python's "flat is better than nested". Since the documentation is continuous work, I could imagine something like "being accurate/up-to-date > being exhaustive"

[lizmat]

META remark: I'm now receiving spam as if there has been a response here. Yet I don't see the spam here. Did someone remove that spam already? Or was it removed automatically?

If it was removed automatically, I wonder why I'm getting the spam :-(

[2colours]

I for one didn't get any notification so not sure what could happen.

[coke]

I got the notifications for here and another repo - the ones on docs were deleted by the time I read the emails.

[opesh]

Something like that

[Arijitdutta19910601]

I am also getting junk notifications. please remove.

[opesh]

Let's come up with ideas instead of feeling worried

[codesections]

Right now, I agree that the docs have a bit of a split personality – or, at least, they're trying to be both a reference and a guide, which is pretty tricky. Unfortunately, I don't see a short-term way out of this; the Raku docs are the only thing close to a comprehensive online reference or tutorial for Raku, so they're stuck trying to play both roles.

For now, that is. Longer term, I'm really hoping that @ash's Complete Course in Raku will become the go-to Raku tutorial and thereby free the docs to be more of a reference. (I know that there are some print books that offer similar tutorial-like content, but it's way easier to link a free resource than to tell someone to buy a book – which, even when well-intentioned, can come across as saying RTFM).

But that's all in the future