Crowd-Contributing a Prolog Cookbook ... an embryonic kernel

Hello,

Eric and I were thinking some time ago about creating a crowd-contribution based Prolog Cookbook. We started drafting something – to seed a very first kernel.

Please find below a link to this first embryonic attempt:

Perhaps via such a google docs, and crowd-sourced contributions something of value can be gathered for the swi community at large …

Dan

5 Likes

How about we, as a community, paste into this document different solution fragments for specific problems, and then explain and organize these into a document structure.

Such a cookbook can become a repository of such solutions and perhaps link to the documentation.

Dan

This is definitely a really good idea. I wonder why a google document?

Could anyone who has enough exerience with google docs do a fast comparison between git (github) and google docs in terms of collaborative editing of a document?

Google doc is very useful for commenting and collaborative work in real time as well.

It is also, in my opinion, easier to write with, since it isn’t a markup language.

Dan

What happens when the document gets larger? Are there any potential problems? I am asking because the only reason I have been avoiding this style of documents is that they gradually become more difficult to edit/nagivate as they grow in size; but I am completely ignorant of how google docs solve these issues.

My knee-jerk reaction would have been to suggest a github repo and a “Github Pages” site but I realize it is probably an overkill and a personal preference.

Hi Boris,

Thank you for asking.

Hopefully, there will be enough community contributions to make google docs less suited and we’ll have to move things to git :slight_smile:

Dan

As for the format, one of the targets might be to (at some point) link from the reference manual to cookbook versions and visa versa. In that light, a wiki or Discourse (which already started a wiki) could be an option. In particular when we move to self-hosting and we can add our own plugins to interlink Discourse and the manual (and maybe SWISH?)

1 Like

Glad we are on the same page.

In digging into and running Discourse if you realize that it is built on PostgreSQL and that from what I am seeing all of the state is maintained in PostgreSQL, I currently see no reason that a complementary site or pages can not be made using the Discourse PostgreSQL database. The toolchain that sits between the SQL and the web page for Discourse is currently Ruby-on-Rails and Ember.js but consider that the toolchain could be changed to using SWI-Prolog. Obviously if the schema of the database changes, the code would have to follow the lead of Discourse but I don’t suspect that that happens often and most of the basic schema I would expect to be rock solid with this many years into production.

EDIT

This is not sugessting that the SWI-Prolog documentation be changed to using the PostgreSQL database but that if you want to have a plug-in that lets you run examples as SWISH in a post, or when you write a predicate signature such as append/3 the text is converted into a link that can take you to documentation in SWI-Prolog, a cookbook page, a SWISH page or working examples, etc. The are many more possibilities but if you put artificial constraints in your path you will miss them.

EDIT

Discourse API Documentation
Setting up webhooks

1 Like

I worked at Google, and used Google Docs extensively for collaborative work, especially design documents. It’s good for people adding comments, getting responses, and updating the doc; also for tracking hundreds of open items. It’s not so good for the final product; we often ended up transforming the Google Doc into some form of mark-up and storing it in the source-control system (which is ironic; originally there were only HTML docs and Google Docs was partly intended to replace them). Google Docs can be a bit chaotic when multiple people have edit rights; it’s often better to grant only comment rights and have a small number of people review the comments and incorporate them (the commentators can always re-open their comments if they don’t like what was done).

Also: Google has a far superior code review and commenting system than github; even so, Google Docs was usually more convenient for reviewing a document.

So, my suggestion is: use Google Docs for getting things started and for certain kinds of editing (especially little things like punctuation); but don’t be surprised if you end up putting it all into MarkDown or similar form at the end.

2 Likes

I know I’m joining this conversation a little late, but maybe it’s a conversation that needs to be resurrected.

I’m very much in the Swish rather than Google Doc camp here. I’ve put together four Swish “recipes” so far, mainly for my own reference and as a backup so I don’t lose them when upgrading my laptop or whatever.

  1. Various ways to iterate in Prolog
  2. Solving Zebra puzzles with Prolog
  3. Compiler Tutorial
  4. Graph Traversal for Problem Solving

I’m not sure what other people have put on Swish, so I personally think creating some sort of “Table of Contents” linking to various tutorials etc would be more user friendly than a Google doc.

Please don’t see this as a criticism of the clear labour of love that Eric and Dan have put into the Google doc, but given we have Swish as a wonderful resource (though I can’t claim to know more than the rudimentary basics) I think we should clearly make it the primary teaching and sharing platform.

2 Likes

Hi Joe,

I think this is marvelous.

I’d rather see this on swish than in a google docs – i just didn’t think of it …

Dan

2 Likes

Actually you are not because this was never meant to have a time limit or be a daily discussion. I am actually glad you jumped in.

With a slight change of the statement to

An interactive programming example is more instructive than a static text example.

you are in a popular group.

This is a great idea, would you like a new category here to collect such? You have to think of a name for the category and if I like it I will create it. We will also need to discuss a few more details if it is to be done on this site, but I am very open to helping with this idea.

It is not seen as that at all, but thanks for the thought. Over the years I have learned that if something is not correct or making progress to just set it aside and start again, or in this case I see no reason both can not be done. While we don’t talk about it here much, one of the main reasons to self-host Discourse is to allow us to extend it beyond what can be done within a Discourse hosted site. (Many thanks to Discourse for supporting us).

Jan W. and the authors of Learn Prolog Now! have visited this idea before with a variation of Learn Prolog Now!.

The main link is https://lpn.swi-prolog.org/lpnpage.php?pageid=online but to see the real difference you need a page like Unification which shows image

See: Does PLDoc have a way to incorporate unit tests akin to Python’s doctest? and specifically this post for more details.

Also Paul Brown started something similar, see: Learn Prolog Now: Request for contribution

There are other post here that also talk about this variation of LPN. (search)

In short you are travelling down a path with many deep ruts while pulling your cart along, but as you proceed you will see many abandoned carts on the side. :slightly_frowning_face:

2 Likes