search

interledger-deprecated / java-ilp-core

WE'VE MOVED: This project has moved to Hyperledger Quilt
https://github.com/hyperledger/quilt/tree/master/ilp-core
Apache License 2.0
16 stars 10 forks source link

Decide where to put usage/readme info #33

Closed sappenin closed 7 years ago

sappenin commented 7 years ago

We need to decide where to put README and otherwise useful information for developer consmption.

One nice example of a Github wiki is the Netflix Hystrix project, where they have light README files and then put most information in the github wiki. Specifically, this wiki page is very useful when trying to use the library in implementations.

sappenin commented 7 years ago

On the previous ILP Java call, we discussed putting documentation for the project into the /docs folder on the master branch, which would allow publishing to Github pages. See the scripts folder in the RFCs project for an example.

@adrianhopebailie Can you provide a little more detail on how this would work exactly? My reading of the Github Pages documentation seems to indicate that we would put generated HTML content into the /docs folder in order to publish via Github Pages. This begs the question, "Where does our markdown content go?". I suppose we could put it that into some other sub-folder, like "wiki" or "markdown" or something? Then, someone would view the rendered HTML content at http://pages.github.com/java-ilp-core?

Overall, unlike the RFCs project, it's not clear to me what this buys us over just writing our README/Examples/Usages documentation in the Github wiki. The wiki is editable directly inside of the github website (in a browser), and is also versioned. I suppose the only thing missing would be CSS styling? But the downside is reading the doco for this project would take the user away from the actual Github project, which is a slight disadvantage IMHO.

adrianhopebailie commented 7 years ago

Overall, unlike the RFCs project, it's not clear to me what this buys us over just writing our README/Examples/Usages documentation in the Github wiki. The wiki is editable directly inside of the github website (in a browser), and is also versioned. I suppose the only thing missing would be CSS styling? But the downside is reading the doco for this project would take the user away from the actual Github project, which is a slight disadvantage IMHO.

The other advantage is control over edits. Edits would have to be made by PRs. The markdown files would also be published to the web, just need to test how that would work.

sappenin commented 7 years ago

The markdown files would also be published to the web, just need to test how that would work.

Sounds good - where do we store the markdown files? Maybe in /docsource?

sappenin commented 7 years ago

I added a wiki-page (for now) to outline the Codec Framework because it wasn't clear where we should put the markdown for the Github Pages stuff. Once that's worked out, however, we can transition away from the wiki (and turn it off).

See here: https://github.com/interledger/java-ilp-core/wiki/InterledgerPacket-Handling-Framework

sappenin commented 7 years ago

Closing this for now - I think once https://github.com/interledger/java-crypto-conditions/issues/48 is resolved for Javadoc, we'll have a better idea if it makes sense to push usage/README into a Github Pages site for this project (java-ilp-core) and that one (java-crypto-conditions).