General notification!
The community members working on the documentation system are deploying
a new refactored system. Hopefully, no one will notice a difference on
the docs.perl6.org page. When the next Rakudo Star is released p6doc
will be working.
However, murphy rules! So some warning ...
The Perl 6 documentation system has developed incrementally over several
years. Problems developed, the most obvious being that p6doc stopped
working.
Two GSoC projects have refactored the system and p6doc works in a much
more intuitive manner.
A number of modules are all in a single repository, and these need to be
split, so that the base Pod6 sources containing documentation about the
language are in one repo, p6doc is in another repo, and support modules
are in other repos.
The main aim of the new work has been
- retain the user-facing interface
- specify the documentation system so that changes to the documentation
software can be tested
- unit tests on software and the documentation
- increased robustness of the documentation system
All of this development work and the rational behind it can be found in
the wiki at the github repo for the docs.
The refactoring has been tested separately, but it will be implemented
for the Perl 6 system in the near future.
Some patience is requested.
In order for Perl 6 to be more widely accepted, it must have a good and
evolving documentation system. As new functionality becomes common in
the software world, the documentation system needs to adapt.
By separating out content sources from the software rendering the
sources, we can allow for new systems to develop.
Not everyone agrees about what is 'good' documentation. So for the
future, flexibility is needed to allow for different possibilities to be
developed based on a single set of source POD6 files, and for software
to be specified and tested before deployment.
Regards,
Richard Hainsworth,
aka finanalyst
