Re: Can the documentation for Unison be migrated from the UPenn site?

I recently struggled to find up to date documentation after discovering the 
move to GitHub, so this is helpful.  But I still found it extremely 
difficult to find the actual documentation in a human readable format, 
especially compared to the old site.

1. I'm using the Unison GUI v2.53.3, which appears to be the latest 
version, on my Mac (macOS Ventura).  The Help menu contains a "Unison 
Online Help" item, which still points to 
https://www.cis.upenn.edu/~bcpierce/unison/docs.html, which only gives a 
404 error. :(  I don't know if this is something that is controlled by 
Unison developers directly, or if someone else is creating the mac 
binaries, but it can lead to confusion.

    1. a. I installed Unison using Homebrew: entering `brew home unison` is 
supposed to take you to the home page of the package, which currently 
points me to "https://www.cis.upenn.edu/~bcpierce/unison/".  Perhaps 
another pointer to update, though I suspect that's an issue with Homebrew 
and not your direct responsibility.  I will look into updating that in the 
homebrew formula, but I'm no expert in that area, either.

2. Going to the GitHub page, I had to read through most of the ReadMe file 
to find the link to the wiki (under "Getting Unison" - but I don't want to 
get it, I want the documentation).  The wiki page itself only contains a 
link to the documentation folder within the GitHub repo: 
https://github.com/bcpierce00/unison/tree/documentation.  This shows me a 
list of files, most of which are not human-readable.  The pdf file is the 
most convenient, but that's still 3 clicks away from the ReadMe on the 
project page (ReadMe > wiki > documentation > pdf file). :(

3. Reading the html file in the documentation directory on GitHub is not 
easy.  Clicking on the file link within the project view shows the raw 
code, which is not user-friendly.  I discovered that you can view it as a 
regular web page by pre-pending `https://htmlpreview.github.io/?` to the 
path (i.e., 
'https://htmlpreview.github.io/?https://github.com/bcpierce00/unison/blob/documentation/unison-manual.html').  
Also, there appears to be no css file to render the html version with the 
similar look as the previous html documentation, but that's minor (and 
perhaps intentional).  

4. There is a note on the wiki that "Release CI artifacts also include an 
appropriate manual", but it's not clear how to find it - I assume it's 
included in the download, but I installed unison using Homebrew, and could 
not find a copy of the user manual in the cache or usual places. :(

I would like to humbly request moving the link to the wiki closer to the 
top of the ReadMe, perhaps in a separate section ("Help" or 
"Documentation"?).
Would it also be possible to add a ReadMe to the documentation folder 
explaining how to actually read the files in GitHub?  Alternatively, a 
direct link to the html and pdf versions of the documentation in the wiki 
would reduce the number of clicks and troubleshooting users need to go 
through to find a readable version.

Thanks for starting and maintaining such a useful project!  

On Thursday, 20 July 2023 at 08:01:28 UTC-4 [email protected] wrote:

> Thanks for pointing this out, Yousuf!
>
> The Unison project has migrated to GitHub 
> <https://urldefense.com/v3/__https://github.com/bcpierce00/unison__;!!IBzWLUs!SKG5mxFighWm7GDe0XVuU3uKx4moOV8bW02Z1yMWlMoSkXPeUxBNlOVygoLwgwtrx-0OB78DB0ZzXUKnEvia954yRLAL1A$>, 
> and up to date documentation can be found there.  I've hopefully now fixed 
> all the pointers from the old UPenn web site...
>
> Best,
>
>     - Benjamin
>
> On Sun, Jul 2, 2023 at 8:36 AM Yousuf Syed <[email protected]> wrote:
>
>> Most of the documentation for Unison is on 
>> https://www.cis.upenn.edu/~bcpierce/unison/, however the documentation 
>> has been down for a month now and can only be accessed through The Wayback 
>> Machine: 
>> https://web.archive.org/web/20230607201850/https://www.cis.upenn.edu/~bcpierce/unison/download/releases/stable/unison-manual.html#unisondir 
>> <https://urldefense.com/v3/__https://web.archive.org/web/20230607201850/https:/*www.cis.upenn.edu/*bcpierce/unison/download/releases/stable/unison-manual.html*unisondir__;L34j!!IBzWLUs!Ww-ETxlz6ocpk1YRANMXXiQL8uGQZ5A_fVMIe9CnIXA34Y3zBuOEfshcpOeXROSXgt4DP6qvrrwsZoxLqTnU9K54$>. 
>> Searching for Unison documentation shows the site at the top.
>>
>> Overall pretty inconvenient to figure out how it works, should the 
>> documentation be moved from that site? How much effort would it take to do 
>> so?
>>
>

-- 
To unsubscribe from this group and stop receiving emails from it, send an email to [email protected].