<various>: Reorganise content about contributing. #446
Conversation
|
I believe you need to remove these files from |
flexibeast
force-pushed
the
move-sections
branch
3 times, most recently
from
d50be7b to
fca78b8
Compare
CONTRIBUTING.md
Outdated
| ### Notes | ||
|
|
||
| Notes should only be used sparingly, and for non-critical information. They | ||
| should begin with "Note: ", and not be block-quoted with `>`. For example, the | ||
| Markdown should look like: | ||
|
|
||
| ``` | ||
| Note: You can also use program X for this purpose. | ||
| ``` | ||
|
|
||
| and not: | ||
|
|
||
| ``` | ||
| > You can also use program X for this purpose. | ||
| ``` |
There was a problem hiding this comment.
Mention warnings around here?
And mention that in most cases the text flows better if using a construct like "It should be noted that..." ?
There was a problem hiding this comment.
Well, i'm not sure #324 was clearly resolved? (And generating the PDF is the sort of situation i anticipated in that discussion, based on my experiences with other projects - the code will be made a bit more complex by having to distinguish warning-bolding from non-warning bolding.) What's your take on that?
Re. notes, so you think we should change this part to just say something like "Notes should be indicated with the phrase "It should be noted that ..."?
There was a problem hiding this comment.
I left a comment there. Most of the discussion is a bit beyond me, though.
Re. notes, so you think we should change this part to just say something like "Notes should be indicated with the phrase "It should be noted that ..."?
I prefer this style, having a Note: feels like it breaks the flow a bit. What do you think?
There was a problem hiding this comment.
I left a comment there. Most of the discussion is a bit beyond me, though.
Okay. i'd like to know @bobertlo's preferences on this.
I prefer this style, having a Note: feels like it breaks the flow a bit. What do you think?
i agree. The more i encounter documentation with visual callout of notes, the more i dislike it. @bobertlo, thoughts?
There was a problem hiding this comment.
i've just changed the style guide's subsection on notes appropriately.
There was a problem hiding this comment.
Great. What did you think of my usage of **Warning**: in the ARM guide?
There was a problem hiding this comment.
That style is probably still my overall preference, so, works for me. :-)
flexibeast
force-pushed
the
move-sections
branch
2 times, most recently
from
25c38e7 to
79e78dd
Compare
flexibeast
force-pushed
the
move-sections
branch
from
79e78dd to
a4410ad
Compare
flexibeast
force-pushed
the
move-sections
branch
from
a4410ad to
0d6e106
Compare
|
PR updated. i believe the only things left to resolve are those in the thread starting here? Anything else? |
flexibeast
force-pushed
the
move-sections
branch
from
0d6e106 to
3d1bdb6
Compare
|
@ericonr: i'd like to merge this. i'd prefer to have these structural changes available sooner rather than later, and not resolving the warnings issue in this PR doesn't leave us any worse off. Any objections? |
* Move contents of `style-guide` and `submitting` to `CONTRIBUTING`. * Move contents of `usage-statistics` to `contributing/index`. * Remove `style-guide`, `submitting`, `usage-statistics`. * Modify text of `CONTRIBUTING` appropriately. * Modify and improve text of `contributing/index`.
flexibeast
force-pushed
the
move-sections
branch
from
3d1bdb6 to
5d05585
Compare
style-guideandsubmittingtoCONTRIBUTING.usage-statisticstocontributing/index.style-guide,submitting,usage-statistics.CONTRIBUTINGappropriately.contributing/index.Addresses #444.