Share your thoughts in the 2021 Clojure Community Survey!

Welcome! Please see the About page for a little more info on how this works.

0 votes
in core.contracts by

There is a number of problems with the way the documentation is made available and interlinked:

  • Currently most people likely arrive to https://github.com/clojure/core.contracts and read the README - but it does not point to the docs in {{./docs/}} => add link to it there
  • It is not clear how the docs are expected to be browsed; I suppose that the .org
    files should be exported to * } yet not all of them are. I also
    suppose that the exported markdown files should be available under https://github.com/clojure/core.contracts/wiki, i.e. pushed to git@github.com:clojure/core.contracts.wiki.git
  • Some of the problems:
     *  the link "return to documentation" on e.g. "with-constraints" should point to /clojure/core.contracts/wiki, not /clojure/core.contracts/docs.html
    
    • if wiki is really exported, the main page should mention it is immutable
    • links on the home page had one more 'wiki' in them (fixed manually in the wiki - will be overriden by the next export)
    • some links are broken, f.ex. (link: defconstrainedfn)(/clojure/core.contracts/wiki/defconstrainedfn) on f.ex. {{contract}}; (link: with-constraints)(/clojure/core.contracts/with-constraints/) (missing /wiki/), (link: defcontract)(/clojure/core.contracts/wiki/defcontract/)

It would certainly help the project if the documentation was easier to access and browse :-)

Thank you

1 Answer

0 votes
by
Reference: https://clojure.atlassian.net/browse/CCONTRACTS-5 (reported by alex+import)
...