Hello,
A good new feature would be to allow user contributed notes in the refdoc.
Indeed, I agree! PHP was where I started and the user contributions in the
PHP doc was priceless. We could solve that with Disqus
disqus is certainly a quick solution, but i wonder if it is good in the long run.
i am concerned about having content that is valuable for us in the hands of a 3rd party.
ideally a comment system would ensure that the comments are under a sharable
license (eg CC-BY-SA) so that comments can not only be moderated but also
modified and improved.
at least it appears that disqus has an export feature so it should be possible
to export comments if needed.
I agree with you Martin. I’ll fix a comments module (well I’m alread y halfway there!) we can use and have more control over the data.
"Edit on GitHub" links are appearing on websites. Having fragments of refdoc pages in a git repo is an interesting concept, which would solve license, moderation and export issues.
In the case of the Elastic page much of that content seems to be generated from the doc comments in the Ruby file which the web page is referencing. So the Elastic site doesn’t seem to have fragments of refdocs on Github, its the actual doc comments in source files that are inserted in the web pages. At least that’s what it looks like to me.
But the Pike beginner’s tutorial on the new site (which I hope to finish in the next comming weeks) works pretty much like you suggest. Those pages are generated from a local checkout of the
https://github.com/pikelang/tutorial repository. If that repo is updated it’s just a matter of pulling in the local repo (which could be scheduled) and the updates will automatically be available on the Pike site.
But we could perhaps use Gists to create a library of examples of various stuff. That would kind of nice.
Regards
-----------------------------
Pontus Östlund
Developer • Roxen AB
+46 70-662 81 69