Revise code block guidelines, add wkls #89
Conversation
Updated guidelines for writing about code blocks. Added instructions for thumbnail images and wkls.
|
Review these changes at https://app.gitnotebooks.com/wherobots/wherobots-examples/pull/89 |
RoboDonut
left a comment
RoboDonut
left a comment
There was a problem hiding this comment.
small change, can be left as is tho.
kadolor
left a comment
kadolor
left a comment
There was a problem hiding this comment.
Generally, I think that a few of these rules (ones that include phrases like "most") need to explain when and how you should deviate from the stated rule. If not possible, including the goal behind the rule to highlight what the specific styling is trying to achieve would be better in order to reduce ambiguity.
| - Anything smaller should probably be omitted or simply emphasized with bold text. | ||
| - If there's text that comes after the heading, put them in the same cell. | ||
| - Put code blocks in markdown cells to show something not also in one of the code cells. | ||
| - Put code blocks in markdown cells *only* when it is not also used in one of the code cells. |
There was a problem hiding this comment.
What's the rationale behind this?
Does this apply to code that includes placeholders and then reinforced by actual executable code?
| - Put code blocks in markdown cells *only* when it is not also used in one of the code cells. | ||
| - Examples: a Pythonic alternative to SQL or something that should be avoided | ||
| - Short excerpts like function or variable names are find, and should get `code formatting`. | ||
| - Short excerpts like function or variable names are fine, and should get `code formatting`. |
There was a problem hiding this comment.
| - Short excerpts like function or variable names are fine, and should get `code formatting`. | |
| - Function or variable names should be enclosed in `code formatting`. |
| - Examples: a Pythonic alternative to SQL or something that should be avoided | ||
| - Short excerpts like function or variable names are find, and should get `code formatting`. | ||
| - Short excerpts like function or variable names are fine, and should get `code formatting`. | ||
| - Use bold only for |
There was a problem hiding this comment.
In the documentation bolding is used for UI elements.
| #### Writing style | ||
|
|
||
| - Focus on the scenario at hand. Use links to docs or other resources for expanded coverage of a topic. | ||
| - When linking to docs, remove any `?h=foo` query string parameters. (This turns off any search term highlighting.) |
There was a problem hiding this comment.
With Mintlify, this issue no longer occurs.
| - When linking to docs, remove any `?h=foo` query string parameters. (This turns off any search term highlighting.) |
| - Use bold only for | ||
| - Presenting or defining a new term. | ||
| - Create hierarchy when adding another heading level would get cluttered. | ||
| - Creating hierarchy when adding another heading level would get cluttered. |
There was a problem hiding this comment.
Could you add some clarification here? I'm not sure I understand the rationale, as .ipynb files provide 6 levels of built-in structural headings.
If a section feels cluttered, it might be a better practice to reorganize it (e.g., start a new H2 ## section) rather than create an informal hierarchy with bolding. The 6 levels should be sufficient.
| - Comments should be one short line and support or expand what's in prose, as opposed to repeating it. | ||
| - Whenever possible, cells should output something. If the cell isn't designed to output already (e.g. a map), provide context or confirmation of what happened with calls like `show`, `count`, or `printSchema`. | ||
| - If needed, follow with a markdown cell with explanation of how the code works. | ||
| - Precede most code cells with with a markdown cell with a `##` H2 or `###` H3 headline to facilitate rapid scanning. |
There was a problem hiding this comment.
| - Precede most code cells with with a markdown cell with a `##` H2 or `###` H3 headline to facilitate rapid scanning. | |
| - Precede code cells with with a markdown cell with a `##` H2 or `###` H3 headline to facilitate rapid scanning. | |
| For example: | |
| > ### Isochrone implementation example | |
| > | |
| > ``` | |
| > ST_Isochrone(geometry, 1, 'car', false) | |
| > ``` | |
Uh oh!
There was an error while loading. Please reload this page.