We need all the help in documentation and its tooling. Richard has been very helpful already, and in fact started the foundational module, Pod::To::Cached, for the new documentation tools, so it will be great if this work can be continued.
Hello.
Firstly, it is not clear from the proposal how much hours will be spent. Considering "a day a week full time" and "work for two months" results in 8 * 4 * 2, which is 64 hours. Calculating the rate it appears to be times bigger compared to a "normal" core contributor and is bigger than a rate of core developers who work on the most tricky parts of Rakudo and MoarVM. Am I correct?
Secondly, some parts of the current documentation system are not optimal in a long term perspective, for example, versioning. There is a 6.c version spec, a 6.d version spec, and preparation for 6.e version spec, possibly more to come. Currently, there are no separation of documentation for them, and changes are noted in different styles, for example "In 6.foo version, this works in another way, foo bar baz". This adds up confusion, hard to maintain and is not very sustainable. A better option would be to have a clear distinction on the site, allowing the user to check the version.
Examples be https://docs.python.org/3/ (a select at the top).
Or http://www.cplusplus.com/reference/cmath/acos/ (tabs with differences).
Or https://docs.oracle.com/javase/8/docs/api/ (a spec of edition 8, but it is there for 7, 9, 10 etc).
This proposal says nothing about the issue and considering the rate, it would be interesting to explore ways to address it.
Thirdly, the same goes for languages (natural ones). There are already some attempts for translating the documentation existing and if we plan to make the language more popular, appearing of translations is inevitable (and we should strive for it). Having means to make it easy is both related to versions and important.
Fourthly, the site search. With all respect, it is known to be incomplete, sometimes inconsistent and have usability issues. For example, even search categories are not standardized.
As coming from an experienced Perl 6 user, I feel like this proposal should address both search consistency and its numerous usability issues.
I do not think I can strongly disagree with this proposal nor I can strongly agree with it, but I had to point out the things above.
Thanks for the feedback. And the questions are all understandable.
a) Costing. I looked at recent grant proposals and at the time spent on them. There have been grants from USD 5000 - 10,000. I have taken $5000 from JJ Merelo's proposal. I have requested that JJ supervises this grant proposal and if he thinks I am not putting in enough work/time, I will work more hours.
b) Triaging the documentation tickets is NOT the only part of the proposal, but it is the one where a concrete mile (inch) stone can be set. The proposal also contains goals for work on p6doc, html & other render formats (via the --doc module switch of the perl6 compiler).
c) Some of the documentation tickets are in themselves quite onerous, and some have already taken weeks of work. For example, to bring the content up to date with 6.d, new pages need to be written for CompUnit et al.
Regarding some of the other requests for the documentation site, namely (a) other languages, (b) site versioning for language version, (c) search functionality.
Multi lingual support is a major can of worms because of the need for synchronising content translations. Since the English content is constantly being changed, currently about a dozen changes a week, in over a hundred source files, and given that translations do not map directly, simply tracking new changes and locating in the other language source files which content needs changing, is non-trivial.
The current approach, which understandably is sub-optimal, is to point to translations of source documents in other languages. These should reference the version of the document collection from which they are made.
The document structure of the documentation pod files would need to be specified in such a way as to make translation synchronisation easier. This is of course possible. But the real question is whether the resources needed to accomplish the goal would not be better spent getting better underlying documentation.
Versioning the documentation collection. The documentation is in the form of pod files in a github repo, which is versioned. In principle, the documentation collection prior to the release date of the perl6 upgrade refers to the current version of Perl 6.
Changes made after the release may refer to both changes needed to reflect new and altered behaviours, and to clarifications of behaviours common to all releases. Correctly identifying what a change in the documentation refers to is not simple.
Both of these requests, whilst apparently reasonable, are bedevilled by details.
Search functionality is included in the proposal under 'look and feel'. Personally I absolutely agree with this request. But making changes to the look and feel are always difficult. Improving the existing functionality is a part of the current proposal. Some of the concrete changes needed have been mentioned in existing issues.
However, I found it difficult to find a concrete goal to cover this sort of intangible progress.
For the difficult requests, eg., multilingual coverage, I see the proposal includes them in so far as I would want to see the problem identified, the resources needed to accomplish some part of the request defined, and some debate amongst developers about the need for these requests.
I do not suggest it would be a good idea to debate concrete changes to the documentation system. The place for requesting desireable changes is in the issues section of the docs repo. Then the pros and cons can be discussed and a way forward agreed on. However, issues then have to be implemented. Getting that done is a part of the proposal as submitted.
Right, $500/day using the community money sounds unrealistic
Versioning of documentation would be something that could be done, and there's in fact a (very old) issue that requests just that. It's not theoretically impossible, and as a matter of fact Perl 6 might be better prepared for doing this thing that other languages, since you can add metadata at the block level.
But.
There are two problems.
First one, there are 400 document files right now, and we would need to add metadata to every block to every one of them. Even if we add metadata only to obviously versioned paragraphs, like the ones mentioned, it would be an impossible amount of (grunt) work. Which would be OK if it pays off.
But.
We'll need to write the tooling to support that. Although right now, with the introduction of Documentable, support for block versioning can be added, well, it needs to be done. Right now we're in the middle of actually implementing Documentable at all levels and redoing all the documentation, and there are dozens of issues related to that across 4 repositories that need to be done, with only Antonio, Richard, Tom and me helping whenever we can. So I don't think that's on the table for the time being, or the foreseeable future.