General Documentation Issues

beerjson / beerjson

Development repository for the BeerJSON format standard

https://beerjson.github.io/beerjson/

MIT License

150 stars 37 forks source link

General Documentation Issues #77

Closed MichaelWashburnJr closed 6 years ago

MichaelWashburnJr commented 6 years ago

In general, the documentation provided so far here is really difficult to read and leaves me feeling more confused than I am just reading through the source code. I feel like this page needs to actually specify the attributes found in a fermentable, hop, etc..

Some oddities I've noticed that are tripping me up:

fermentables says its an object, but appears to be a list in this example
I would expect a Fermentable to have a list of attributes, but none are listed, and the link to FermentableType 404s.
Recipe Types as defined here seem to have the attributes that a recipe has. I'm not sure what the difference between RecipeType and Recipe is, comparing examples to documentation

I'd love to start diving in to get an official release of this out, but I'm finding it hard to grasp the concepts. It seems like there's a need for one page which specifies the schema in its entirety, including fermentables, fermentable types, hops, hop types, recipes, procedures, equipment, etc.

pricelessbrewing commented 6 years ago

Related to issue #13.

Is this corrected in the documentation refactor pull request by krutlin?

superroma commented 6 years ago

Hi, I'm still working on the generator, so most actual docs are in this branch: https://github.com/beerjson/beerjson/tree/gen-docs-rewrite It is not complete, but I'll look at reported issues in coming days.

MichaelWashburnJr commented 6 years ago

@pricelessbrewing It's certainly related, but definitely not corrected. Although now I know the right place to get involved. I'll leave any additional feedback on PR #13

MichaelWashburnJr commented 6 years ago

As a follow up, @superroma Have you found writing code to generate docs based on the .json files to be more tedious than just writing the documentation by hand? In my experience, having a human in the loop with regards to documentation generally makes it more readable and useful. Although more care has to be taken to make sure it's updated when the specification changes

superroma commented 6 years ago

At this point schema is changing a lot, so generating docs is much easier than updating by hand. We not generating descriptions, just an overall structure.

In the future it might require a hand written long pieces of markdown, but I think we can handle this case in generator by having some kind of include directive.

superroma commented 6 years ago

I have merged latest docs into master. There is still issue #79 is open, but all other shemas should have a documentation generated.

pricelessbrewing commented 6 years ago

@superroma Having issues with this, how do we run gen-docs.js ? I keep getting error below, I need to generate document for #51 before submitting PR.

Edit: Got it. Run below as per \docs\README.MD

npm run gen-docs

pricelessbrewing commented 6 years ago

@beerjson/beerjson-wg While I don't know how much I can help with the generator, I plan on going through and adding descriptions to anything that needs a description to help fill in the documentation a bit more.

superroma commented 6 years ago

I think I've fixed all issues with documentation.

Currently we don't process nested object property type definition like this one: https://github.com/beerjson/beerjson/blob/87325891351d62f0db2a6e5699589d2c329a0735/json/culture.json#L75-L91

I suggest extracting such definitions into its own type and leave a reference there.

So, i guess we are ready to add missing definitions.