search

SoarGroup / SoarGroup.github.io

Soar's website: documentation, news, announcements, links, etc.
http://soar.eecs.umich.edu/
Other
7 stars 3 forks source link

Duplicate Documentation #41

Open moschmdt opened 1 month ago

moschmdt commented 1 month ago

I noticed that there are three (or more?) versions of very similar documentation:

  1. Soar debugger help command for the explain and chunk commands. I assume this must be located either in the Soar CLI or Soar Java Debugger code?
  2. Usage instructions in chapter procedural knowledge learning
  3. Soar CLI reference for explain and chunk commands on the website.

Points 1. and 3. probably apply to all CLI reference commands.

garfieldnate commented 1 month ago

1: yes, it's located directly in the Soar code.

2: I think we can safely replace that with a link to the reference page. I don't know how that will look when we generate the manual from the website, though.

There is also a number 4! The wiki: https://github.com/SoarGroup/Soar/wiki. We actually download from there to write the manual sections currently: https://github.com/SoarGroup/Release-Support/tree/master/ManualSource/wikicmd.

The documentation website is essentially a GitHub wiki, so I want to get rid of 4 and replace it with 3.

In turn I would also like to unify 1 and 3, with the website being the canonical version. I'm thinking of some system where we can format the CLI references properly on the website, and then we would periodically run a script in the Soar repo to pull the latest text, format it as needed, and place it at the correct locations in the code. Would also be nice to print something like "view on the website at ..." when running in Soar, as the long texts can be hard to follow in the terminal.

moschmdt commented 1 month ago

2: I think we can safely replace that with a link to the reference page. I don't know how that will look when we generate the manual from the website, though.

I will have a look at it and add this to #40. I think keeping the image in the section or adding the image to the reference page is reasonable?

In turn I would also like to unify 1 and 3, with ...

That sounds reasonable, but is the full text even necessary in the CLI or is a reference to the canonical version sufficient? As you already mentioned, the web version is probably easier to read, so in my opinion a link/ reference would be sufficient. In general, this sounds like the man pages project in unix systems - maybe that or a cpp CLI library is a feasible approach?

garfieldnate commented 1 month ago

I think keeping the image in the section or adding the image to the reference page is reasonable?

I'm not sure what image you're referring to, but if an image works well in the reference section, then yes, I think moving it over and linking to it makes sense.

is the full text even necessary in the CLI or is a reference to the canonical version sufficient?

I do think having the full text available there is important. Many users use Windows, so a Unix man page would not suffice, and Soar is also used in contexts where general internet access might not be available (think defense industry). Also, the website doesn't have versioning yet, so its contents are always newer than whatever version of Soar was last released, which could be confusing for users unless we start adding notes about what Soar version a particular option was added. I just don't want to make waves here. The formatting or where exactly in the distribution we store the data could definitely be iterated on, though.