Attending: Daniel, Geoff, JJ, Liz, Nick, Stefan, Vadim
- For corporations that want to donate to TPF/TRF/YAS
- Bullet point summaries both for future plans and for past achievements
- Drafts for both summaries circulated to RSC, collecting feedback
- To be finalized by our next RSC meeting
- Some people believe current doc site is out of date
- There is at least general agreement that there are a lot of problems
- ... but not necessarily how they should be addressed and when
- One volunteer has built a major overhaul
- Huge amount of work done already
- But wanted to make many changes at once:
- Redesign, UX, source templating, deployment method, etc.
- Other folks wanted to do only single changes at a time
- Recent discussions have gone around in circles and then fell apart
- Direct connection been JJ and major volunteer led to compromise
- Doc source compatibility between before and after will be maintained
- New site will go up as a new beta
- People will be pointed at the new site
- Lots of details decided, but RSC needs to decide on:
- Domain for the beta doc site
- Do we need a "manager" specifically for the docs site(s)?
- We have a LOT of open issues on the doc site right now (hundreds)
- Many of these are for content
- These are not being addressed in any systematic way
- Right now there is really only one person who can successfully generate the full doc site, because of use of a deprecated code highlighting engine
- Some would like to have a plan to move at some point away from having permanently multiple official sites
- The precedent of raku.land versus m.r.o has shown us that community-built sites can effectively replace "official" sites anyway
- There a lot of use cases that the current docs system doesn't handle
- ... and it seems to miss the mark of its own target audience
- Though maybe the reality is that the docs have lots of different target audiences and people coming from different other language communities, expecting different things from docs
- We should also be careful that serving both beginners and advanced users
is difficult to do at all well for both at once
- We could have a "beginner book" format, with links to the "how it really works underneath" docs
- Things like IDEs want to be able to on-the-fly use the doc information, not the page renderings
- Comparison to major web sites that when they change design, offer an
'old.foo.com' that keeps the old design for those who prefer it
- This absolutely requires compatible data to be scalable at all
- ... and a compatible (or reasonably mappable) URL namespace
- Since this kind of thing is likely to happen more than once, we'd need
a naming convention that would allow multiple versions
- docs.$name.raku.org ?
- Perhaps multiple versions in community, but only one is "official"?
- This absolutely requires compatible data to be scalable at all
- Offline documentation needs some attention
- ... as discovered when our site was unreachable
- github.com/rakudocs.github.io has a generated version of the current static site
- Dynamic versus static (but generated) site
- Static valuable from security point of view
- Dynamic allows some capabilities that are otherwise difficult
- Dynamic site might be slower without significant caching/precomp
- In which case, almost a return to static site anyway
- But we've actually gotten this working decently for the irclogs already
- Could also do static pages, but provide an API that other sites can use
- Generally content is our biggest overall problem
- It is hard to get more people to fill in all the gaps in the content
- The depth of Raku means there's a lot to do
- We don't have corporate sponsorship for docs
- A better doc site that is easier to work with can encourage people
- People want to be able to very easily do edits, not needing to fork and PR
- What about TRF grants for building docs?
- What about converting our GSOD applications into an RSC grant proposal?
- That way people don't need to risk putting lots of effort into applying for a grant with no idea of probability of success
- People contributing new features have a problem dealing with version/release
dependent doc changes
- There may be value to having "releases" of the doc tree, in sync with Raku/Rakudo releases, specifically so people can PR into the future release
- At least want to be able to plan that important feature changes have docs by the time they are released into the wild
- AI: Split static Pod6 content from other parts of the existing docs repo
- Need an additional side discussion to go through details of how
- AI: TRF grant proposal
- AI: Problem-solving PR suggesting naming