Convert static site to dynamic site

[coke]

It would be nice if both the local and installed website used the same engine to serve out pages. (The installed site could use a caching proxy to improve performance).

There are two benefits to this that I see:

1. Ability to eliminate many of the $COLON (etc.) substitutions that we make in URLs - we could still make them in filenames, but then automatically map the URL request to the file name. (File name mangling is needed to run docs on certain file systems safely - we then have to mangle every corresponding URL with the current system)

2. Ability to add dynamic search.

Another potential benefit is that we don't have to generate the full set of HTML docs as part of the build, we can do it as they are requested (but only if we have a caching solution in place).

With a cache, we can also potentially use a Perl 6 engine to serve the content.

[coke]

Related to #698

[tisonkun]

@coke How is it going?

[JJ]

Ping...

[JJ]

This would be related to #2542. Now that we have Cro, it wouldn't be too difficult to do. But rendering the final HTML, either statically or dynamically, is still but a single phase of all that needs to be done.

[coke]

I think @Altai-man mentioned they were working on this on IRC.

[Altai-man]

Correct.

[codesections]

I am very confused by this issue. I've been following it for some time, but my understanding has been that this issue was related to improving the search functionality and perhaps offer an alternative for users who want to generate the docs locally. If that's the goal, then I support this issue.

However, some recent discussion on the #raku-dev IRC channel now has me confused. That discussion makes it sound as though some people read this issue as about replacing the current doc website in its entirety. If we are beginning to consider such a move, then this repo isn't really the correct place to be having the conversation; that's a pretty major change that should be discussed and agreed upon in the Problem Solving repo.

[Altai-man]

@codesections

I am very confused by this issue

I'll describe what I think of it, please don't consider it as mocking or something, I am acting on a good will now.

The title says "Convert static site to dynamic site". Currently, HTML pages for docs are generated and served as is, so a static website. While this approach has its benefits and is simple to do (I mean, docs were started at times when Cro simply did not exist, tooling was non-existing, people wrote a basic Pod::To::HTML convertor and since then it was growing without any control into legacy everyone is afraid of, I am being blunt here), it has obvious drawbacks. This issue is one of the issues demanding someone to make this step to get better routing, potentially a better search. There are also tickets demanding better UI, examples execution and all that.

that's a pretty major change that should be discussed and agreed upon in the Problem Solving repo

I have a pretty bad experience with the problem solving repo.

IMO the case is simple: the existing website we have needs a from scratch maintenance and someone who can solve tickets, making it better.

People generally agree the website UI is less than awesome, #3470 #3055 #2429 #2138 #1090 Raku/doc-website#112

There is a demand for a better search: Raku/doc-website#386 #1410 Raku/doc-website#112

There are various features to play with or just requests "Make it Raku", "Make it dynamic": #2910 #1866 Raku/doc-website#199 #1057

Those tickets go back to 2016, it is not like the problem has emerged magically yesterday, it's the solution (I hope).

When I started to work on a new website, I talked it over multiple times with @JJ, he saw the design mockup iterations, provided feedback, I also noted it on IRC multiple times (I agree I was not screaming about it, but it is normal when you have no idea if you can heavy-lift something so hard as it was).

Thus my stance on this is:

• If people prefer to generate static docs for themselves, generate e-books, serve alternatives etc - they are welcome to do so. It is not like the tooling disappears, all of this will add more variety. This is a good thing.
• The current website state is... I don't want to use some adjectives, but I guess one can look at it and see for oneself. What is clear is a demand to update it.

Instead of a problem solving repo, can RSC discuss this? As there is a demo now available, let's just compare it to other alternatives by simple metrics: what looks cleaner to the reader UI-wise, what has more usable features, what has better support of mobile platforms etc.

[Altai-man]

Why I don't think a problem solving repo is a good idea: IME it usually goes as follows:

• You see something is broken so hard it pains everyone.
• You implement a solution which solves the problem.
• You go to the problem solving repo.
• Create a ticket about a problem everyone knows about already.
• Write up a solution instead of doing the actual work.
• Besides a couple of papercus that can be fixed in development it is agreed on
• You do all the work
• The problem solving repo process fails because the people have no time to gather and approve, I guess you saw The PS-process' acceptance policy doesn't match reality problem-solving#272
• You wait silly 2 weeks that the solution could be deployed with people being happy about the thing becoming less painful
• Don't want to do it again ever.

[Altai-man]

To be clear: I do agree the problem solving repo is important for really important things: language design decisions, legal issues etc. But the current documentation website (its appearance and the tooling behind it) not being nice enough is a fact (you can be polite and say "Oh, it is OK, maybe it just needs some tiny patching", I prefer not to), but it is not ambiguous.

In case of the language design, you can do various trade-off, choose one option over another with various benefits, but with the docs website you will have a really hard time arguing "No, static files are great, let's just close all the tickets that disagree with it, nobody wants example execution, nobody wants sane routing".

[codesections]

I'll describe what I think of it, please don't consider it as mocking or something, I am acting on a good will now.

Thanks very much for the explanation! That makes a lot more sense now :-) And I 100% understand that you're acting with good will and I very much appreciate your hard work 👍

I believe the brackets below accurately paraphrase what you're saying, but please correct me if I got anything wrong:

[The redesigned website is designed to solve three general problems:]
[1.] People generally agree the website UI is less than awesome, #3470 #3055 #2429 #2138 #1090 Raku/doc-website#112
[2.] There is a demand for a better search: Raku/doc-website#386 #1410 Raku/doc-website#112
[3.] There are various features to play with or just requests "Make it Raku", "Make it dynamic": #2910 #1866 Raku/doc-website#199 #1057
Those tickets go back to 2016, it is not like the problem has emerged magically yesterday, it's the solution (I hope).

I also hope that a new docs website along based on your proposal is the solution! Personally, I think it does a great job of solving 1 and looks very promising (though still WIP – e.g., extended search) in solving 2. I have some concerns (again, speaking personally) about the approach to 3. and plan to open an issue on your repo to provide details on my thought process there – but that shouldn't take away from the great work you've done on 1 & 2.

(Maybe others won't share my concerns on 3; if they do, I'm sure we'll be able to work together to come up with a good solution.)

Your comments about the way the Problem Solving process has worked in the past are well taken. Imo, none (or almost none) of those problems should be true of the Problem Solving process; I hope we can get it working well enough one day that future issues like this can be productively discussed there. But I recognize that it hasn't yet gotten there and can understand why you decided not to get bogged down in that process.

I also agree that discussing this in the RSC is a good next step. In the week before our next meeting, I plan to get familiar with your proposed site so that I can hopefully have a more informed opinion on it. Once again, thanks so much for the work you put into this – it really does look great 💯

[Altai-man]

though still WIP

Yes. As I wrote at the announcement, I just don't have a lot more money or energy to spend on this and I hope people will help to make up the small bits remaining after all the heavy-lifting is done.

have some concerns (again, speaking personally) about the approach to 3

Sure thing, we can improve it. I think the structure is pretty clear (not considering some bits of legacy, but I can grunt through it if necessary), so solving issues should be so much simpler now compared to the old website tooling people are afraid of (as finanalyst wrote, "the more I looked at Pod::To::HTML and Documentable, the more I hated them" and I get him too well).

(Maybe others won't share my concerns on 3; if they do, I'm sure we'll be able to work together to come up with a good solution.)

Yes.

I also agree that discussing this in the RSC is a good next step. In the week before our next meeting, I plan to get familiar with your proposed site so that I can hopefully have a more informed opinion on it

Yes. As I said, it has some missing bits, but given a couple of people with right skills spend a couple of hours - a lot of the problems will be solved and it will be not worse than the current website we have in any position and a lot better in a number of positions.

Feel free to ask questions wrt the website.

I will also write up my stance on the situation with finanalyst to not sweep this under a carpet.

I did not want to make anyone sad with this, in fact I see people saying the result looks ok enough for them (some say it looks good, but that's a flattery). I think his Collection modules are great as a tool for generation of static websites or converting POD6 into other formats. It appears to me like it is similar to e.g. Doxygen project as I wrote on IRC: it collects the code documentation as POD6 and creates documentation pages automagically for you. Any project can use that, they can be easily hosted afterwards.

But if you intend to replace the current website entirely and feel sad when someone else suggests that, why not drop a note anywhere about the intent? Maybe in this issue, saying "Maybe we don't need a dynamic site, here is what I did".

Even without this, I fail to see how my work renders his work obsolete or useless: Doxygen is not becoming obsolete just because there is a Java documentation website and I regret causing pain.

I would not be able to write such a tooling as he did, clearly. But I was able to do a different thing, to put up a website and e.g. hire a designer to draw up the UI. I think people should do what they can and if one is great with writing tooling and another can write websites, they can do their best in different areas.

Otherwise it looks like nobody pays an attention to open issues in the repo for years, but when someone provides a solution for the tickets - they get a backlash of "Why are you fixing it, keep it as usual".

/me is waiting for the news from RSC.

[jonathanstowe]

FWIW, I'm not in favour of the original premise of this ticket in its entirety, that is the local documentation is served up by basically the same web server that serves up the docs web site, IIRC SCO OpenServer did this back in the last century and it was a mammoth pain in the arse for administrators. But a common generation codebase would be a definite advantage.

I think a thing that might be appropriate for "Problem Solving" is a common mechanism for generating installable documentation (e.g. man pages,) that would be available to packagers.

[Altai-man]

@jonathanstowe I think there is a https://github.com/Raku/rakudoc project for dealing with the documentation locally. If anyone is interested in contributing, the efforts should go there, it's an open way for people to tackle this interesting problem, IMO orthogonal to how the website looks or behaves like.

[jonathanstowe]

Yeah but the original premise of the ticket was that they should be one thing 🤣

[Altai-man]

@jonathanstowe it does so only partially, but includes other interesting suggestions as well, so it is a bit mixed.

[patrickbkr]

I am now sort of reusing this ticket to discuss how to proceed with Altai-mans changeset to the documentation website. From memory and half knowledge the changes are:

• Switch the templating system from Template::Mustache to Cro::WebApp for speed
• Largely redesign the HTML for aethetic and usability improvements
• Strategically move the default operation mode to dynamically generate the HTML on request instead of precompiling pages to pave the path for versioned docs, redirects and some other features.

JJ has voiced concerns about the complexity of these changes.
Altai-man is more willing to invest his resources into working on the software itself than discussing on if, which parts and how these changes should be merged.

Given the documentation pages (Pod) themself are cleanly separated from the software stack that creates a website (I think they are, but haven't checked in detail), then I think a good way forward could be to for now proceed with developing Altai-mans approach separately and host it with a separate name. This would:

• free Altai-man (and possibly others) to usefully continue working on the documentation website. The site would be online and could be enjoyed by anyone wishing to do so.
• not endanger the stability and simplicity of the good old docs.raku.org site.

Should parts of the then (possibly only temporary) separate site prove robust, useful and manageable they can be migrated over to the old docs page. The separate site would then act as a test bed.

The documentation itself (Pod) could either only reside in the current repo and be auto imported into the separate deployment or git could be used to keep the copies in sync.

ps. Bikeshedding the name: metadoc.raku.org 😛

[coke]

Thanks for bumping this.

Hosting with a "real" secondary name makes it seems as though it's intended to stay separate. Can be something truly temporary (not even under raku.org), with the thought that it will eventually replace the main doc site.

My opinion: I would prefer the dynamic site to replace the existing static site. Were I Altai-man, I'd be concerned about putting effort in to something that JJ is going to reject. If there are specific objections, let's get them listed and addressed one way or the other. My first concern is hosting: easy to host a static site; do we need our devops involved for the static site? Any issues with cost?

[JJ]

My main concern here is that this issue is proposing a solution for a problem that might probably be solved in some other way. Let's tackle them separately

• The $COLON|$SOLIDUS thing was a possibly temporary hack to be able to index fragments of the documentation and link them independently. They're awkward, but the main thing they have going for them is the backwards compatibility. It's not so much a problem, but a solution to something that might or might not be a problem. Do we want to index and link directly the .? operator? Do we want to link and include in URLs stuff that never, ever, should go in an URL like slashes and dots? If the answer is yes, well, we have to deal with that. And we can deal with that in a dynamic and static site; the current Documentable does make a job that, if not perfect, it's at least consistent with the reverse-engineered functioning of the previous htmlify.p6.
• The ability to do dynamic search. Again, this is something that right now is solved, rather hackly, with a huge JSON that's dynamically searched in the client. No requests to the server, no overloading, no API, no nothing. Fast and inmediate. I don't see this a problem per se right now. There are many problems with search. We probably need to tackle them, but I don't see server-based search as being inherently better than client-based search (I can be proved wrong, of course).

Right now, generating the full set of HTML is not such a big deal. Biggest issue is that you need a specific version of node to make it work, because highlighting is irremediably obsolete. The fact that we need JavaScript for that is another issue, of course. If we could somehow hack the Comma engine to generate highlighting for us that would be great, although I think it's Java-based (as IntelliJ stuff) is wont to do...

Just my 2¢

[Altai-man]

From memory and half knowledge the changes are:

That's the overall picture of what was done in more details:

• Made Pod::To::HTML extensible, previously it had a very hardcoded template of the results made exclusively for how the current website is organized, so it was vastly improved to make every bit of it extensible, make concurrent usage robust (previously it was not possible reliably). It had global variables before. : /
• Reviewed current state of the doc sources, discovered the search anchors usage had no proper usage policy and in fact was misused in hundreds of places (so we are writing search anchors in Pod but most of the writers had no idea how to do it correctly). Introduce a standard of search categories (see Documentation search categories are not standardized problem-solving#250). This required numerous changes to the docs and some changes in how to process it to make the end result consisting. The new system also warns about misuse.
• Reviewed existing tickets about issues with the documentation. Used the old tooling (Documentable) and not re-inventing the wheels to create a new website that would resolve or pave a way to resolving 33 tickets in total. From them 9 are about search and 5 are marked as big, others are related to how the website looks like.
• Iterated with @JJ the new UI that looks professional, claiming Raku is not a toy or a clown language but something you can trust.
• Implement features like code samples execution with live editing or a top level search page with search by category, color schemes.

[Altai-man]

Mi main concern here is that this issue is proposing a solution for a problem that might probably be solved in some other way.

The $COLON|$SOLIDUS thing was a possibly temporary hack to be able to index fragments of the documentation and link them independently. They're awkward, but the main thing they have going for them is the backwards compatibility.

My main concern with this is that the cure is worse than the poison in this case. There are universal rules about how to escape characters in URLs. All the sites use those rules. Browsers know how to deal with them, how to show them pretty etc.

But then we out of blue create some ad-hoc, "temporary hack" solution creating scary URLs instead of just using the standard of how to escape things.

And if we want to preserve the backward compatibility you care about (so do I), it's all the reason to have a way to describe the redirects easily with a dynamic engine. Right now the backward compat has no means written for people to contribute anywhere except for maybe some htaccess files maintained somewhere somehow.

Citing you (Raku/doc-website#198):

The problem is that much of how URLs are generated is a hack. In the case of ..., main problem is that you can't have . in an URL.

Yes, it's a hack. Why not do it properly while preserving the backward compat and live on with a cleaner state?

We probably need to tackle them, but I don't see server-based search as being inherently better than client-based search (I can be proved wrong, of course)

I will be bold to correct your statement a bit: on my website client-based search is used AND it has a lot of the tickets you mentioned resolved. No requests to the server, no overloading, no API, no nothing. Fast and inmediate.

[Altai-man]

Should parts of the then (possibly only temporary) separate site prove robust, useful and manageable they can be migrated over to the old docs page. The separate site would then act as a test bed.

We had this version of docs live for months and months and it led to nowhere. Well, if you want we can spin it up again on some obscure url nobody visits. I suspect just like the other time another year will pass and all the issues driving the small pool of users we have away will be there for one more year. I guess we have all the time in the world to wait, right? : )

[raiph]

[Please ignore this comment.

This comment was a strawman proposal outlining a particular A/B approach that was intended to very simple. The feedback was that even the simple thing I suggested was too complicated. I've left this stub so if anyone wants to see what it said they can click Edited above left.]

[JJ]

Raiph, would love to do that, but we simply don't have the resources for that. I already proposed @Altai-man to just set it up somewhere, under some appropriate raku.org domain (maybe metadoc, as @patrickbkr said), and try and see how it works.

There are so many sweeping changes, from the structure of the documents to how they are rendered and delivered, that it's going to be impossible to keep compatibility even at the source level. So the A/B testing would consist essentially in which repository gets the most contributions and is kept so much up to date, I guess.

[patrickbkr]

Should parts of the then (possibly only temporary) separate site prove robust, useful and manageable they can be migrated over to the old docs page. The separate site would then act as a test bed.

We had this version of docs live for months and months and it led to nowhere. Well, if you want we can spin it up again on some obscure url nobody visits.

I envisioned we (maybe only temporarily) serve and promote a separate docs page, similar to e.g. raku.land. This would hopefully lead to a userbase and thus prevent the risk of all of the efforts to be throw-away work, because in the worst case of the changes not being deemed suitable for inclusion in docs.raku.org it can just happily continue living as a separate page.

In general:
I'm fine with the process of incorporation of the changes into docs.raku.org continuing instead of going for a separate page. I actually prefer that solution.

But:
In case this project again manages to end up in a deadlock situation (as happened in the past for multiple reasons I hope we can avoid to discuss) then I think working toward a (potentially only temporary) separate page can be a way out of the deadlock.

[raiph]

Hi @Altai-man,

Iirc I didn't like some things about your site back when I last looked at it and you had said it was a take-it-or-leave-it proposition. (If I'm mixing up this site / you with another one / someone else then the rest of this paragraph is irrelevant.) I didn't want to create noise, or create work for others that I wasn't committed to doing myself if no one else wanted to, so I stayed quiet. This is a principle I stick to; I stay shtum about many things in such scenarios. This was despite the fact I thought the site was in some regards a big improvement, and despite feeling it had clear potential to be better in all regards, though I recall you (if I've got the right site / author in mind) expressing some opinions very strongly that I (silently) disagreed with.

This time around, I feel the same, but am speaking up in an attempt to break the deadlock.

What about making the domain name for your site be doc.raku.org? It's still obscure in the sense that all existing resources link to docs.raku.org, but maybe a compromise you could live with?

Also, could we change the template for docs.raku.org to have a colored bar at the top that links to (preferably the closest matching page in) doc.raku.org? (No need to mention it, for the reasons I outlined in my earlier strawman proposal.) And the new site could have a colored bar that explains it's a beta of a new doc site and directs readers to click the corresponding bar on the existing site if they wish to redirect to the new site.

This would have two effects: A) makes it easy for folk to start using the new site and B) relatively quickly gets the new site and its pages into google's search index. (AIUI there are ways to accelerate that; I'd be willing to try help with that acceleration.) Even if nothing else was done for a month or two, the situation might well be much better once google searches begin to show results from both sites, and those who don't know there's a difference between the two sites don't need to care, and those who are surprised when they see there's two sites will easily see it's a good thing and how to switch between the two.

[Altai-man]

In case this project again manages to end up in a deadlock situation (as happened in the past for multiple reasons I hope we can avoid to discuss) then I think working toward a (potentially only temporary) separate page can be a way out of the deadlock.

Alas, it won't, it's not a solution in any way.

We have a problem: the current website is known to have lots of issues in how it handles, erm, almost everything.

Because the number of issues is big and it roots deeply, I had to spent my time changing a lot of things, not because I am a huge fun of spending my time rewriting what works perfectly, but because the issues go so deep you cannot monkey patch them in 2 minutes.

You suggest we can put up another website somewhere, but the problem we have (issues with the current website, where people go to docs.raku.org and see them) won't disappear cause of another website appearing. Not today, not tomorrow, never, it just won't happen.

It is a known thing the doc project lacks contributors. We can try to re-vitalize things, showing people we are working on improving things, thus inviting them to join. But we can also create even more forks we lack time resources to contribute to - that's what is suggested and I cannot agree.

What I really don't understand is why do we even need to search a compromise. Imagine a situation when there are some bugs in Rakudo. Someone comes around and tweaks them, sends PRs, the bugs are fixed. But the PRs are rejected due to (something along the line of) "We are not sure if there are better solutions, can you just fork Rakudo and try to entertain people with it?". Even if I do, the original Rakudo still has bugs, they are still there. From the current course of how things are going, it doesn't look like the issues with the docs will be fixed next week or next month. For a year I was inactive the horse is still there. For years the horse it still there and yet we're somehow in a situation when we are picky "oh, yes we have some old dirty temporary hacks, but we're living with them, so why fix things? Can't we have it the old way?".
This really boggles my mind.

[Altai-man]

Iirc I didn't like some things about your site back when I last looked at it and you had said it was a take-it-or-leave-it proposition

Alas, I don't remember anymore. : )

If the suggestions were something along the lines of "I don't like the template here and here, change it so and so" I could've reacted awkwardly for sure.

If they were more of the technical side of things, "take it or leave it" is a strange thing. I certainly remember one person suggesting a new raku.org design with such a statement, yes. As for me...

The thing is, when I spent a half of year mending everything, I thought once I'm done with this huge bit, people will thank me for cleaning up old hacks, so I'll be able to contribute on top of this foundation to fix other huge issues we have, like documentation versioning or highlighting or whatever in the time after that.

But it turned out to be such a huge let down with people showing up claiming they don't need this because they have a better solution WIP (spoiler: they did not), being called names, being constantly treated as some kind of aggressive criminal because I insist on fixing issues instead of the "just go with the flow, do nothing and you won't make a mistake, the old hacks work, no need for something else" approach, with all this dragging for months of talking. I am not 100% sure I have the old enthusiasm anymore.

Say it is not a "take it or leave" position, yet I don't feel safe with working on the docs versioning issue knowing the people concerned would block it.
Say after 1.5 years I'll finally be able to push it through. Ok, we updated the website. What's next? Spend 3 months fixing something else and then another year trying to convince people the issues have to be resolved? The whole reasoning about contributing is somehow broken. People spend their time fixing thing nobody wants to fix, it should take as little "overhead" efforts as possible. Looking at the current situation, don't you agree it's the opposite right now?

This would have two effects

This is a technical compromise. I don't feel bad about it. In fact, it sounds like a cool idea for the migration process.
The problem is, this crisis is less technical than it is a "community" one. We have issues, they are not resolved by those concerned, stale issues. Say some people are willing to contribute, but they would be blocked. The issues remain. It's clearly about politics, not about technical compromises. How to proceed with this and make it peaceful again - no idea.

[patrickbkr]

It's clearly about politics, not about technical compromises. How to proceed with this and make it peaceful again - no idea.

But would not a separate page based on a separate project also provide a workaround for the political issue? A separate project can have a hugely lower bar of getting changes in and can thus be easier to contribute to. Should that different approach of managing contributions prove more fruitful, then so be it.

You suggest we can put up another website somewhere, but the problem we have (issues with the current website, where people go to docs.raku.org and see them) won't disappear cause of another website appearing. Not today, not tomorrow, never, it just won't happen.

But if that other website gains the favor of users and developers it will.

[coke]

Some bullet points, as I am sick right now and not able to turn this into a coherent essay:

• I am in favor of getting the dynamic site up and running and moving to that framework.
• I also have been frustrated with how planning for the current site is done over the past few years. Proposals (not just mine) have been rejected in favor of other steps which often do not come to pass. This has definitely impacted my desire to work on the site.
• We already have been reduced to a small number of developers working on non-documentation issues (this is not due just to attrition). Blocking someone who has demonstrated a clear desire to improve things is not going to improve the situation.

My proposal (all of which mentioned earlier in this thread), given that we have what I think is a working implementation of a dynamic site that also fixes some long-standing issues with the existing site and unblocks others:

1. Agree that we want a dynamic site, and that this one is a good starting point.
2. Spin up the new version again at a staging location, specifically so we can:
3. Test it, identify any issues, classify them as blockers to be fixed, or nice to have. @Altai-man not expected to be the only person working to resolve these issues
4. Once all the blockers are fixed, deploy new version to the existing URL.

To be clear:

• 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.
• I suspect these changes are too much for an A/B test - and if we're low on resources to come up with a coherent approach to the switch, I don't see how we can get a real A/B test designed and in place to addresses specific items.
• I think it might be time to open a RSC issue about how the docs site is being managed.

[JJ]

Some bullet points, as I am sick right now and not able to turn this into a coherent essay:

* I am in favor of getting the dynamic site up and running and moving to that framework.

* I also have been frustrated with how planning for the current site is done over the past few years. Proposals (not just mine) have been rejected in favor of other steps which often do not come to pass. This has definitely impacted my desire to work on the site.

I have many pain points. This proposal for standardizing the URLs was created a long time ago, it's still there. We would need to agree on a standard format for URLs, because what we have now is reverse engineered from the original script. That's not been done. Without a standard format for URLs, we will still generate weird URLs and/or drop others that are already being pointed at, static or dynamic site.

This one was approved after a lot of work by everyone involved, it's not been acted upon in the current site and tooling as far as I can tell. Categories were a pain point, since they were generated by just putting some indexing in some specific format. That was (more or less, at least in a agreed way) fixed. It would have been great to incorporate it into the current tooling. That's not been done.

* We already have been reduced to a small number of developers working on non-documentation issues (this is not due just to attrition). Blocking someone who has demonstrated a clear desire to improve things is not going to improve the situation.

My proposal (all of which mentioned earlier in this thread), given that we have what I think is a working implementation of a dynamic site that also fixes some long-standing issues with the existing site and unblocks others:

1. Agree that we want a dynamic site, and that this one is a good starting point.

Don't agree with that, but that's beside the point

2. Spin up the new version again at a staging location, specifically so we can:

3. Test it, identify any issues, classify them as blockers to be fixed, or nice to have. @Altai-man not expected to be the only person working to resolve these issues

4. Once all the blockers are fixed, deploy new version to the existing URL.

That's precisely what I have proposed above, and proposed again in the specific mailing list a long time ago.

* I think it might be time to open a RSC issue about how the docs site is being managed.

By all means, please go ahead. Let me just remind you that it's "managed" by everyone who's got the privs. At the end of the day, what we're talking about is simply a matter of putting up a new site and telling the infrastructure people to have a raku.org domain, even the old domain, pointing at that. There's not a single person that can decide on, or reject that. So by all means, please go ahead.

[sdondley]

From a managerial perspective, I'd posit that 100 motivated people doing imperfect work will get a lot more accomplished then a handful of unmotivated people doing perfect work. Wikipedia is a good example. Even bad contributions can be valuable because they can always be changed and improved later.

I don't see why the doc project can't have the same outlook. It's not mission critical.

[patrickbkr]

• I think it might be time to open a RSC issue about how the docs site is being managed.

@coke @JJ Just to be sure I understand correctly. Are you talking about a problem-solving issue or about pining the RSC to get involved?

[JJ]

I've requested the RSC to add this as an item for the next meeting, taking place this Saturday.

[coke]

I've requested the RSC to add this as an item for the next meeting, taking place this Saturday.

Thank you. I was happy to see the direction things were moving in later comments, appreciate it.

[codesections]

I haven't had a chance to comment in this thread in a while but I've been following it closely – and, as @JJ mentioned, we discussed it at today's RSC meeting. Based on that discussion and this thread, I prepared a PR that (I hope) will satisfy many (hopefully all!) of the points raised in this thread while hopefully also giving Raku flexibility for the future.

I look forward to any thoughts you may have ☺

[Altai-man]

I did the updates to run the website.

One interested can host it somewhere, there is a docker-compose file - https://github.com/Altai-man/docs.raku.org/blob/master/docker-compose.yaml

Alas, I don't have energy to organize the work on this, to plan what issues are immediate, the passion is long time gone.

I can however work on the issues brought up based on what we have up: just link the old or new tickets for me to work on, it'd be easier to get back on track this way.

[Altai-man]

@coke @patrickbkr maybe you are interested in ^

[Altai-man]

So I just hosted it myself: http://164.90.207.89:10010/
Again, ones concerned should work out the tickets to resolve to get it moving somewhere.

[coke]

@Altai-man , thanks.

Let's review this instance, we can keep track of any issues noted with the new site here, and then figure out next steps.

First comment: I definitely like the updated look.

Suggestion: when reporting issues, please include not only a description, but also an indication of severity. If we're considering a switch from the current site to this version, we need to know if the issue raised is a blocker, wishlist, or something in between (and if it could be fixed after a switch instead of before)

[Altai-man]

@coke thanks!
As for the tickets, there are issues in the website repo, so the tickets should go there. Also some old ones are still there, probably should be reviewed.
Ideally tickets in this repo are content only imo.

[coke]

Can you link to the website repo in your comment above?

[Altai-man]

https://github.com/Altai-man/docs.raku.org/issues <-

[coke]

The new new site is being handled via doc-website.

The next incarnation of the site will be able to run dynamically while developing & testing in Cro, but currently is setup to run in prod statically. (can run this way for dev also)

If we want to pursue fully dynamic vs. static again, we can re-open the request on doc-website.

Thanks to everyone for their efforts in pushing us towards a new, more easily maintained site, regardless of the dynamic vs. static consideration.