Add basic usage documentation - readme

[goofballLogic]

First steps for #11. Note that other PRs will follow to provide example use cases (samples).

[codecov]

Codecov Report

Merging #62 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master      #62   +/-   ##
=======================================
  Coverage   68.59%   68.59%           
=======================================
  Files          22       22           
  Lines        4053     4053           
  Branches     1028     1028           
=======================================
  Hits         2780     2780           
  Misses       1130     1130           
  Partials      143      143           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a98b12f...7450cc2. Read the comment docs.

[goofballLogic]

@asbjornu is this heading in the right direction?

[goofballLogic]

Codecov appears to be borked for this PR. Do you know anything about codecov @asbjornu / @wattsm ?

[asbjornu]

This is awesome! Just mark it as done once you're ready for a review.

I'll take a look at Codecov once time allows. It's not set up as a required check yet, so we can ignore it until it's in 100% working order.

[goofballLogic]

All code added to the org here: https://github.com/linked-data-dotnet/json-ld.net-Demo

@asbjornu if you feel it shouldn't be in the organisation I will remove it again. Was looking for some way to make it easier to update the README in future.

[asbjornu]

I think this is a great first start! Awesome work, @goofballLogic!

I know it hasn't been discussed, but I think Remark defines a great set of both guidelines and tools to keep Markdown documents in good shape. Now that we are adding quite a bit of Markdown to this repository, I think it would be good to standardize on formatting rules and commit them to the repository. Since that isn't done yet, I would still like to address some of the things I care about and that Remark (by default) is going to complain about anyway.

All code added to the org here: https://github.com/linked-data-dotnet/json-ld.net-Demo

Awesome!

@asbjornu if you feel it shouldn't be in the organisation I will remove it again. Was looking for some way to make it easier to update the README in future.

Two thumbs up from me! 👍 👍

[goofballLogic]

Have added basic descriptions of the various algorithms and utility methods

[goofballLogic]

I will squash most of the commits once you are happy with the outcome @asbjornu

[asbjornu]

This is fantastic work, @goofballLogic! Thanks for investing the time necessary to get this done.

I think we need to strike a balance here between our personal preferences and discouraging contributions from others.

I agree.

When considering what makes it easier "to read as plain text", I think it very much depends what you are using to access the text. Certain editors, terminals and shells do a good job of providing line wrapping facilities, and manual line wrapping can sometimes prevent users taking advantage of the facilities at their disposal. On the other hand there are the line-oriented editors and piping tools (I happen to be a fan of vi) which benefit from short discrete lines.

Yes, I think plain text rendering benefits from an 80 character limit, if only to reduce the line length to a readable amount.

I don't mind doing the work but I do think we need to settle on a reasonably small set of well documented rules for contributors to follow. I would like to see more community involvement in this project going forward if possible.

I find that most developers mimicking the style used already, unless they are completely unfamilar with Markdown, in which case any standard could be seen as a benefit or hindrance.

I'll go ahead and make the changes suggested, but can you think about putting together a short guide for contributors?

Yes, absolutely: #70

Is the requirement to alter the code itself to adhere to a 80 character limit also? Some of these code examples will need a bit of an overhaul to fit within that narrow limit if so...

No, it only applies to text written in natural language.

same applies for the link references - I'm not sure how to keep those to 80 characters as the URLs are longer than that limit in some cases. Maybe there's some markdown black magic for this?

No, that's one of the many positives about using link references instead of inline links, as you can just have as long links as you'd like down at the bottom of the file without affecting readability one ounce.