Request for Feedback: Perl Documentation Site
The official Perl documentation site at https://perldoc.perl.org was recently overhauled. Independently, I put together a reimagined documentation site that would be hosted at https://perldoc.pl. In the interest of providing a documentation site that best serves the needs of the Perl community, we need your feedback. Please give both sites a try, in-depth if you want, or just how you would most commonly use the site. What do you like about the design or the functionality of each site? What is missing or can be improved? Any feedback regarding what you want from the Perl documentation site is helpful and appreciated. Please leave comments here or in the linked posts by Monday Nov 18th.
I blog about Perl.
What are the weaknesses you are trying to overcome?
I certainly agree that lots can be done to improve the perldoc website, but none of them are leaping out at me on your revision.
Very nice work! A couple of things come to mind after a brief glance:
perldoc.pl is kind of hard to navigate. The manuals section of perldoc.perl.org contains more stuff that I likely want to see.
I couldn't find perlre on any of the sites. Yet I think it's more important that, e.g., "Utilities".
Do we need line numbers and syntax highlighting for the code snippets? Both seem to add very little value.
On mobile, I prefer the styling on perldoc.pl that doesn't line-wrap code. Personally, I prefer horizontal scrolling over reading wrapped code.
Now that perl is on github, links to GH could be added to each page of documentation to make it as easy as possible to create pull requests or bug reports.
Your effort is very worthwhile, thank you for this. I guess the more the documentation, the more tricky it is to find what you might need. Some kind of analysis that allows assessment of whether the visitor found what they were looking for or not would be useful feature to train an intelligent search. Metrics that identify which are the most commonly searched items also yield interesting insights.
It is also difficult for small groups of people to manage huge volumes of text. Allowing community editing of sections is probably a way around this. This also allow incorporation of links to other sites which may provide more targeted help.
Different people need different densities of help. Being able to differentiate between quick help and detailed help might be also of benefit.
some formatting issues in the code displays
For example `$#days` the 'days` gets formatted as a comment.
My goal was primarily to resolve or avoid the issues brought up in the GitHub issue tracker (both the old and new ones). Beyond that, it is just personal preference, so we want to know what your (collectively) preferences are.
Its a good thing to move on. I really liked the new doc site, easy to use and navigate through.
Might I suggest to add something like ClickHeat (or pay for mouseflow) to help determine how people are responding to the page layout?
Such a tool would help identify peoples unconscious behaviors and provide science instead of peoples preferences.
Gathering more data in a scientific manner is a good idea, but tangential to what we're trying to find out here. Data won't explain what people like or don't like about the style of the site, or what they wish they could accomplish more easily. Could you elaborate on what you think can be done to improve the site?
I prefer perldoc.pl. Took me way too long to find "quotes and quote-like operators" on perldoc.perl.org.
You might like to plug in something like "mouseflow" (paid) or similar. ClickHeat seems to be the only foss one that i have come across. They are extremely helpful in working out whats valuable on the screen and what isnt.
In terms of design & layout inspiration, readthedocs.org/io is very popular - so people are accustomed to its layout and possibly its layout is well conceived.
In fact someone could probably feed perldocs in to it and see what it looks like.
I like the non-official site somewhat better, but I can't explain why.
A glitch from the past was that a lot of links didn't work on autogenerated files. I couldn't find any failures in my brief attempts, so maybe that has been fixed.
I prefer perldoc.pl, it's much better than perldoc.perl.org, although tbh I'm not a big fan of its design, it isn't *bad*, but it's slightly too gray and depressing for my taste.
A few random things I like about perldoc.pl:
- perldoc.pl has much better search, I especially like its special handling of perldeltas. Also the fact that I can input a punctuation variable in the search box and it just takes me to the right place in perlvar. I use that all the time.
- perldoc.perl.org is buggy, the bug Karl mentioned is still there and it's pretty serious. For example, go to 'bless' documentation and try clicking on the link to 'ref'. It doesn't work. It was reported *years* ago and it's still not fixed.
- perldoc.pl is more up to date, 5.30.1 was released a week ago and perldoc.perl.org still doesn't have it.
- I like that perldoc.pl provides blead documentation. Thanks to that I don't have read PODs straight from perl's git repo to check whether the documentation issue I've just found was already fixed or not. It saves time.