problem-solving
problem-solving copied to clipboard
Raku
Solution for Raku/doc/issues/1246
This PR proposes a solution to Raku/doc/issues/1246. (I now realize that issue was in the doc repo rather than the problem-solving one and thus technically I should open an issue in this repo and discuss the matter here before opening a PR. Since that issue has been active for 5 years and has generated the a similar discussion as it would have as a problem-solving issue, I believe it can stand in for an issue in this repo. But if anyone objects, I can close this PR and do this by the book.)
Specifically, this PR would allow alternate documentation frontends such as the one prepared by @Altai-man to have a home on the raku.org website (at docs.$new-site-name.raku.org). It would also provide a list of all such alternate frontends, some guidance about creating new ones, and a note that an alternate frontend could one day become the new primary doc site. Please see the solution document for full details.
I personally support this PR. But from my understanding this PR proposes roughly the approach that Coke and Altai-man objected to.
Quoting Coke:
I think that setting up a second version of the docs site long term is a waste of time and splits our already limited resources, even if both sites are working from the same source docs. If the existing team has concerns about the new site, let's get them specified so they can be discussed/addressed.
Quoting Altai-man:
[...] we can also create even more forks we lack time resources to contribute to - that's what is suggested and I cannot agree.
I think it is also worth mentioning, that Raku/doc#1246 did to a large extent discuss the broader and underlying topic of how contributions in general are handled for Raku/doc. This PR does not address this. I think it's important to not evade the issue by now going forward with the proposal of forking the docs website and not answering the general "How do we want to handle contributions?" question.
Some points I'd like to make:
- Yes. We do not have enough people working on documentation.
- The MAIN issue is really that there are content issues (not enough / errors)
- There are few people happy with the documentation site as it is.
- This situation has been going on for many years now, burning out people.
- The PR is trying to break the stalemate that has developed.
The PR tries to address points 3,4,5. It frees up people willing and able to put in time in working on the presentation of the documentation content. And it will allow them to get credit for their work that they have put in in the past, and will hopefully put into it in the future.
I think the argument of it "spreading what little resources we have, don't spread it even more" is wrong. At the moment we're burning out what little resources we have because their work on a new layout is not being appreciated (Richard Hainsworth and Oleksandr Kyriukhin in particular) and the discussions about the layout (which is burning out JJ Merelo, and has me burned out on this subject).
It is my hope that a better representation of the documentation, with potentially more features, will get more people to see that the content will need fixing as well. And thus addressing points 1 and 2.
Compare this to the situation with the ecosystem: aka https://modules.raku.org vs https://raku.land . The raku.land website has more features than modules.raku.org, and I'm pretty sure that the more attractive layout (and the fact that it is pure Raku and open source) will help people to decide to make more content.
Yes, it's not ideal.
Finally, as a reminder. Just as anybody can implement a version of the Raku Programming Language that passes the test-suite, I think that anybody can make a Raku Programming Language documentation site as long as the documentation matches the results of the Raku test-suite. Having a single source of the raw content, just make this easier, but it is certainly no prerequisite.
@patrickbkr thanks for those quotes – they show that my initial PR message didn't do enough to explain how (we hope that) this solution is consistent with @coke's and @Altai-man's views (especially the parts you quoted). So here's a bit more explanation:
As the quotes show, there's widespread opposition to a long-term fork of the docs site/maintaining multiple official versions of the site. I 100% agree that multiple official versions of the site would split our already over-burdened resources.
At the same time, there's also a split in what the official site should be/look like: everyone wants to improve the visuals, but some people want to switch to a dynamic site while some want to keep it static (while maybe adding dynamic features via API calls). Without a consensus on static versus dynamic, we've had extended conversations but no real progress – which is also a distraction from actually improving the docs's content or presentation.
Thus, the goal of this PR is to find a way to unblock everyone without creating a long-term fork or committing Raku to maintaining multiple versions of the site. This PR tries to achieve both by saying the following:
- Raku will not have multiple versions of the docs site – it will just have one.
- This one official site will be built in a way that makes it easy for anyone to make their own nonofficial version.
- The Raku community won't have any responsibility to maintain these nonofficial versions; all it will do is to list them in the
READMEso that rakoons can find them. A - If any nonofficial version gains enough support, it could become the (single) official version.
The hope is that this will unblock folks to experiment in a Raku-style "forgiveness > permission" way without splitting our resources into multiple official sites.
Of course, it might be that even nonofficial versions of the doc frontend split Raku resources; in theory, any time that put into making a nonofficial version could be put into the main doc site. But this PR – and, really, much of Raku's development – operates under the premise that volunteer time is non-fungible: just because someone is willing to volunteer their time to make their own frontend (a fairly fun/empowering project) does not mean that they'd be willing to do the (very important but less fun) work involved in maintaining/improving the existing site. Thus, so long as we avoid committing Raku to maintaining any nonofficial versions, we're hoping that any effort that rakoons put into those alternate versions will come "for free" rather than out of a budget that could be used for the official docs site.
Finally, I'm also hoping that letting rakoons maintain their own alternate versions of the docs site may actually encourage more work on the main site/the docs content. My personal sense is that at least some people might help improve the contents of Raku's docs but are put off by the current site's presentation. If so, linking to nonofficial versions might encourage some of those rakoons to improve the current docs.
At least that's the theory. I'll certainly understand if not everyone agrees, but I hope the above at least clarifies why I viewed this PR as a compromise solution rather than as "propos[ing] roughly the approach that Coke and Altai-man objected to". All that said, this is just a proposed solution and I look forward to hearing other thoughts.
Don't have time to answer properly now, but in short I don't mind it (this PR).
@JJ If I understand things correctly, you put down your official responsibilities with respect to the documentation and created a (personal?) fork of the docs. If your fork is meant to be more than a personal copy, then this is contrary to what this PR proposes (having multiple doc frontends, but keeping a single documentation).
I do notice and hope to understand the difficulties that caused this decision. Nevertheless I think it's important to clarify the state of the different documentation repositories.
Do you consider https://github.com/Raku/doc/tree/old-docs a personal fork?
@JJ If I understand things correctly, you put down your official responsibilities with respect to the documentation and created a (personal?) fork of the docs. If your fork is meant to be more than a personal copy, then this is contrary to what this PR proposes (having multiple doc frontends, but keeping a single documentation).
I didn't have any "official" responsibilities, other than taking care of the documentation issues in this repo, a position from which I'm proposing to be relieved: #322
If not using the same source is not in the spirit of this solution, I'll simply refrain from requesting an "official" domain. I'm happy with the one I'm using now.
If not using the same source is not in the spirit of this solution, I'll simply refrain from requesting an "official" domain. I'm happy with the one I'm using now.
If with "domain" you are talking about "https://github.com/Raku/doc/tree/old-docs" then this is well. Do note that I was not asking about hosting of the docs website, but about forks of the documentation itself (not the webfrontend).
If not using the same source is not in the spirit of this solution, I'll simply refrain from requesting an "official" domain. I'm happy with the one I'm using now.
If with "domain" you are talking about "https://github.com/Raku/doc/tree/old-docs" then this is well. Do note that I was not asking about hosting of the docs website, but about forks of the documentation itself (not the webfrontend).
That's not a domain by any definition of the word. You referred to this post, which vows to give docs.xxx.raku.org domains to those that use different front ends. You said that a fork is not a different front end, to which I responded that I will not request that kind of domain then.
That's not a domain by any definition of the word. You referred to this post, which vows to give docs.xxx.raku.org domains to those that use different front ends. You said that a fork is not a different front end, to which I responded that I will not request that kind of domain then.
I'm a bit confused now, but I think we agree. So just to make sure: https://github.com/Raku/doc/tree/old-docs is a personal fork and as a consequence general work on the text of the documentation should continue at https://github.com/Raku/doc. Right?
. So just to make sure: https://github.com/Raku/doc/tree/old-docs is a personal fork and as a consequence general work on the text of the documentation should continue at https://github.com/Raku/doc. Right?
Documentation work should continue on the master branch of raku/doc, yes. The domain/sites discussed in the thread are for hosted versions of the website, and the primary site will continue to be generated from the master branch.
I disagree with "alternative-versions" of docs hosted under raku.org.
From a outside view this looks like we are unable to maintain one, so we need many? And it will confuse people. "Which one will be the documentation site, who describes raku?"
If one like to to play around with different layout or different features, you may host this yourself and declare it as "non official".
I would rather prefer bundle forces on improving docs.raku.org itself.
Sidenote: If raku.land is the better modules.raku.org, why not moving raku.land to modules.raku.org namespace?
Sidenote: If raku.land is the better modules.raku.org, why not moving raku.land to modules.raku.org namespace?
Yes, please! I was totally unaware of raku.land until someone mentioned it in an RSC meeting. Why keep an (afaik) unmaintained, less capable page around, when there is something better available?
Sidenote: If raku.land is the better modules.raku.org, why not moving raku.land to modules.raku.org namespace? Yes, please! I was totally unaware of raku.land until someone mentioned it in an RSC meeting. Why keep an (afaik) unmaintained, less capable page around, when there is something better available?
I think keeping old things around is the result of a flaw in our current decision making process. Currently no one feels responsible for modules.raku.org, people sometimes make changes, but noone sees themself as reponsible. Thus no one is willing to take the decision to remove it. I have seen this effect one time or another in other areas as well. I think things are improving now that problem-solving and the RSC started their work.
I personally like the name and domain raku.land. So I'd be in favor of a redirect modules.raku.org -> raku.land (instead of moving raku.land to modules.raku.org).
I would suggest the vertical "Author" problem should be fixed before there's a redirect.
I would suggest the vertical "Author" problem should be fixed before there's a redirect.
The respective bugreport: https://gitlab.com/raku-land/raku-land/-/issues/21
The solution is not difficult but some work. The idea is to just rename all raku.land internal HTML IDs by adding a should-never-collide prefix. I guess merge requests are welcome.
Can you please report back on the status of this issue? It has been 5 months.
@2colours in the end, we need just a little push to instantiate the new website in place, but there were no volunteers to do it lately. Helping out is welcome, it's more about organizing and pushing people to do things rather than the actual heavy-lifting.
@Altai-man Sorry, I got a bit confused about docs.raku.org and raku.org overall... are we talking about the docs site you have been working on?
Anyway, I do notice that the main problem is the lack of management at the moment, even more so than the lack of resources (I think you have pointed this out some time back, referring to indefinite pending times of PR's). However, for myself, I don't think I have the kind of trust that is required to take management tasks in hand, even if I have some ideas regarding it, and a lot of people are available so indeed it might only be a matter of "pushing".
If there is anything I can actually do on my own, please let me know, that would be a net win. :)
Sorry, I got a bit confused about docs.raku.org and raku.org overall... are we talking about the docs site you have been working on?
The ticket as a whole is about docs.raku.org.
Anyway, I do notice that the main problem is the lack of management at the moment, even more so than the lack of resources
Yes.
However, for myself, I don't think I have the kind of trust that is required to take management tasks in hand, even if I have some ideas regarding it, and a lot of people are available so indeed it might only be a matter of "pushing".
Trust is not required, we're all internet denizens here.
If there is anything I can actually do on my own, please let me know, that would be a net win
As I already mentioned, organizing efforts of the present members, or being a locomotive to do everything on your own (this one is arguably harder).
The ticket as a whole is about docs.raku.org.
I noticed that in time; this doesn't answer the question. :P
I noticed that in time; this doesn't answer the question
are we talking about the docs site you have been working on?
Yes, at least I do, cause the whole issue was originating by this work. This website ("my", though various people worked on it...) is the only de facto solution we have which solves the tickets.
Yes, at least I do, cause the whole issue was originating by this work. This website ("my", though various people worked on it...) is the only de facto solution we have which solves the tickets.
Thank you for the reminder on this, need to move forward still with infra team.
Thank you for the reminder on this, need to move forward still with infra team.
As we lacked meeting lately, I notified lizmat (which was reflected in latest weekly) that since next week I feel obligation to force the new website into life, as opposing opinions lack efforts to back them up, so if you have time this weekend, we can sync up and see if there is anything urgent.
As we lacked meeting lately, I notified lizmat (which was reflected in latest weekly) that since next week I feel obligation to force the new website into life, as opposing opinions lack efforts to back them up, so if you have time this weekend, we can sync up and see if there is anything urgent.
+1
Closing this PR as effectively the new documentation site has been live for a while now.