Splitting guidelines #547
Splitting guidelines #547
Conversation
Original authors credit - @olensmar and @jasonh-n-austin
| @@ -275,7 +203,7 @@ To include these parameters, you would need to add them individually as such: | |||
|
|
|||
| Again, Operations can be shared across files. Although the reusability of operations will be less than with Parameters and Definitions. For this example, we will share a common `health` resource so that all APIs can reference it: | |||
There was a problem hiding this comment.
For this example
The example is missing...might be best to eliminate this intro, or move it to JSON_References.md
|
I wonder if we should do a GitBook specification. It's very easy on the eyes, hierarchical by default and it should align pretty well with our plans to take this large monolithic document and break it up. This is more of a general idea than a review of this PR. |
|
Well, shame on me for not paying attention to the details. Will get those fixed. Any thoughts on the split itself and whether it should be done at all? @whitlockjc never heard of GitBook before you mentioned it now, so no opinion there. |
|
After reading through this, I'm not convinced it's a good split. There's a lot of duplication of content, and the guidelines don't read well without inline examples. |
|
Fair enough, @jasonh-n-austin - not overly concerned with pushing it. I'll try giving it another go and see if I can make more sense of a split, but if it feels artificial, then there's no point to it. If we don't do the split, I'll probably submit a different PR to slightly organize the doc (links, topic rearrangements...). Will ping for additional review in that case. |
|
Closing for now. May revisit in the future. |
With the additional information about JSON References, perhaps it makes to have a dedicated guideline page for JSON References. It would help users who seek that information specifically.
Original authors credit - @olensmar and @jasonh-n-austin