In search of a place to host documentation

[aarroyoc]

During the meetup and some previous discussions, there was the idea of starting hosting some documentation for the project. @mthom said that a Wiki was probably a good idea, however, it is not the only option. Here are a few:

• Use GitHub Wiki. It's already there. However, right now, only Mark can write things as it is set to "Only collaborators". This makes it very difficult for other people to collaborate. Wiki can be opened for all GitHub users or just for some collaborators.
• Host docs in the same repo. Another option I've seen in some projects is to have the docs in a folder and changes are normal PRs. There's a workflow on GitHub Actions that generates an HTML site and uploads them to GitHub Pages. This option would require a little bit more initial work. However, I think it makes the workflow of writing easier and it could be later integrated with some tool to generate API docs. Also, I think it would be more discoverable (better SEO).

What do you think? I personally prefer option 2 but maybe there are other interesting options out there.

[triska]

I agree that pull requests are better, since they can be easily reviewed, commented, linked to etc.

So, I would also suggest option 2, documents in the same repository. They can by Markdown (*.md) documents, like the README, and Github will automatically display them nicely.

[infogulch]

Maybe with a bit of CI we could have both. Note on the wiki page the "Clone this wiki locally" section -- wikis are git repos too. I'm imagining we could have a /docs dir in the "main repo", and whenever its contents changes it kicks off a CI script that copies it over the "wiki repo" so it stays up to date. Admittedly having it saved in the Wiki area is only a small benefit over just navigating to the /docs directory yourself, but it would still be nice for new user discovery and casually browsing. And it could transition smoothly into publishing via gh_pages instead.

[infogulch]

Another idea I think would be neat is creating a prolog documentation generator for prolog code, and then using it to add code documentation to the libraries that is then generated into the docs folder via CI. It seems like it could be an achievable, useful "dogfood project" for scryer, to me at least.

[mthom]

I feel very strongly that developer docs should live on the github wiki (and perhaps elsewhere but first and foremost wiki). They're in a very distinct category of documentation apart from user docs.

[aarroyoc]

These are very interesting concepts to keep in mind when working on documentation: https://diataxis.fr/

[infogulch]

I like this model because it highlights four good modes/types of documentation. Each type is based on and clearly delineated by its usefulness to a particular kind of user with a clear goal, and the user's goals are neatly organized along two axes: working-studying and theoretical-practical.

I'd seen it first at https://documentation.divio.com via 1. I'm unsure what the relationship is between these two sites but they are very similar, identical in part.

An improvement to the system (and I think necessary to fit into this project) is admitting an additional user-developer dimension (arguably independent from the other two), as indicated by Mark.

[jjtolton]

Curious if this discussion is referring to information about the Scryer Prolog program or about how to write programs in Scryer Prolog? For my own education and to get to know other folks in the community I'm trying to consolidate best practices for writing Scryer Prolog programs, but aside from the discussions forum, I'm not sure where the best place is currently to put those documents.

Has this been solved/decided here/elsewhere?

[aarroyoc]

I added support for custom pages. You can see an example here: https://www.scryer.pl/learn/test-page . They are defined in the doclog.config.pl file

[bakaq]

Incredible! This really enables a lot of cool documentation stuff. I think a start would be to migrate a lot of the "tutorial" documentation that is currently in the README (like how to use the toplevel) to this format.

[jjtolton]

I added support for custom pages. You can see an example here: https://www.scryer.pl/learn/test-page . They are defined in the doclog.config.pl file

You should** add support for GIFs too cause

is how I'm feeling! 😁

**(should not lol)

[bakaq]

@aarroyoc, just letting you know that the library links in the sidebar are broken. The link for library(dif) for example goes to https://www.scryer.pl/scryer-prolog/src/lib/dif.html, but the page is actually in https://www.scryer.pl/dif.html, and in the example import it shows :- use_module(library(src/lib/dif)).. The "browse source" links are similarly broken.

[aarroyoc]

Thanks a lot @bakaq ! I solved the issue and I'm running a new deployment to fix it ASAP