Skip to content

Home

Jump to bottom Edit New page
Will Coleda edited this page Dec 10, 2022 · 85 revisions

Welcome to the raku/doc wiki!

This page shows the roadmap related to Raku documentation, both for volunteers (see Community below) and interested parties.

If you are working on something for Raku documentation, please be sure it's listed here; Please also join to the monthly status call (Second Saturday every month at noon Eastern time at https://meet.jit.si; room: raku-docs) to discuss ongoing efforts or to get involved!

Needed

Any authors or editors greatly appreciated. Stop by #raku-doc on IRC to chat; If you can't, an email on perl6-users will eventually find us, or submit a PR to start a conversation, or start a github discussion, etc.

Blockers

Any issues currently considered blockers for ongoing work

Issues

fix html build

Deprecated: we are moving forward with the dynamic site listed below.

The HTML build requires some specific versions, and the build instructions don't match the README.md currently. While this was considered a blocker, we are going to move to a new build currently under development, so resolving this issue is no longer a blocker.

Any content changes made until the site cutover will not be reflected on the existing site, but will be as soon as the new one goes live.

Projects

Dynamic site

There has been a long standing request to consider migrating the site to a dynamically generated one instead of a statically generated one. There is an effort started some time ago that is available for testing:

This site includes many changes, however, not just static to dynamic: new styles, runnable code snippets, updated search, JS, and is considered a potential solution to several logged issues.

The blocker right now is getting infrastructure support to rollout the new site; There is also some onboarding going in devops which will eventually increase capacity but is currently another mini blocker.

RSC

Many items raised in this RSC meeting

The issues list and this wiki itself contain many requests, wishlist items, potential improvements, and bugs. Need to map these out into specific action plans, some of which can be resolved by PRs already in progress, some which will require discussion, and some which require a simple matter of programming to resolve.

Documentable

Master of Documentable is not compatible with master of raku/doc; the new dynamic site is using a branch to work around the issue.

Part of adopting the new dynamic site should include updating master on Documentable; we should also discuss if Documentable is intended to be used by anyone other than consumers of raku/doc and generating an html site.

Community

IRC

#raku-doc - Logs

Meeting

There are a limited number of folks working on Raku/doc and related issues, and it's important that we communicate as a team. Starting in May of 2022, we've had a monthly call to stay in touch and coordinate on planning for the roadmap. be some sort of (probably) monthly "call". Contact info for the call will be posted here, and please reach out on #raku-doc on IRC.

Next call: December 10, noon Eastern time.

Squashathons

Squashathons - we used to be able to get folks together regularly to hack on raku/rakudo/doc issues, but this seems to have stopped. We should probably remove references to this from our meta docs: #4066

(Actual) Documentation

Any tickets tagged "Docs" should be for updates or new documentation. We should consider a separate tag for tickets that impact the documentation but are not about a particular feature, e.g. marking which version a feature is part of, and yet again about editorial concerns about styleguide changes, etc.

Recommendation of ordering:

  • Existing submitted documentation PRs, e.g. #4047
  • Anything simple so we can close the ticket
  • Checklists for release information in reverse order (newest first)
  • Oldest tickets first

Documentation in related projects: Should also consider efforts around:

  • nqp opcode documentation
  • moarvm architectural documentation

Site

There are several issues related to the docs.raku.org site; These include some major project items (above), but also potential changes to styles, presentation, bugs in certain browsers, etc.

Ongoing Work

After every Rakudo compiler release, we should

  • Create a ticket from the ChangeLog with a checklist for each documentation-worthy change
  • Update the required Rakudo version to run the test suite in xt/01-raku-version.t
  • Cut a documentation release? #2690

Recent Changes | Atom

Raku/doc wiki

Home

Misc

Minutes

Archive

Clone this wiki locally