search

makerdao / community

Contains current and historical governance polls and executives used in the governance of the Maker Protocol. Previously contained a lot of other content which remains in the 'prior-cleanup' branch.
https://forum.makerdao.com/
GNU Affero General Public License v3.0
192 stars 161 forks source link

Updated Contributor README.md for word choice, etc #231

Closed aburban90 closed 4 years ago

aburban90 commented 5 years ago

Made a HackMD for this: https://hackmd.io/6DPtf2OyQJCv9OJYw_rqjA

@ghettodev @Davidutro Improved word choice/phrasing. Ran thru Grammarly. Added periods in lists to stay consistent with the style-guide. Removed first and second person voice where possible.

Under Project Description, added a link to style-guide. Was just the words "can be found here" before, and no link to anything. @ghettodev Did I put in the right link?

Made minor changes to "How do I get involved?" section. See for changes to bullets.

This section below, I am completely lost on. It reads so poorly, but not sure what to do to it:

Is this for me?

Github: https://github.com/makerdao/community/blob/master/contributing/README.md

Davidutro commented 5 years ago

I think we need to talk about selective use of the second person language.

@as-dr and I both had thoughts that using second person in pages that speak most directly to community members and contain calls to action.

The second-person is less appropriate in the "matter-of-fact" type docs like FAQs or pages that are trying to get across impersonal information.

Thoughts @ghettodev ?

Davidutro commented 5 years ago

@aburban90

It's hard for me to tell the changes that were made when it is a stand-alone Hackmd file. If you make changes to any documents just submit the PR, we can always edit the commits after you submit the PR .

A PR would make it way easier to see the changes made.

aburban90 commented 5 years ago

Funny... seems like the opposite of what @ghettodev told me lol ...that, the hackmd is easier to go back and forth on changes.

If you go into version history... I'm not sure to what degree it tracks changes, but I initially copied in the original file, and then started making changes. Maybe it'll let you compare the first pasted version with the latest?

I can also just submit a PR for you to see the changes though, and then we edit in the hackmd once you see what the changes are.

aburban90 commented 5 years ago

As for first/second person... I really don't know what we prefer. Generally, for my writing, I try to avoid it as much as possible. Sometimes though, it just becomes really ridiculous rewording things to avoid using that language.

This is probably something that should go in the style guide, but we need fairly specific rules.

Davidutro commented 5 years ago

Funny... seems like the opposite of what @ghettodev told me lol ...that, the hackmd is easier to go back and forth on changes.

If you go into version history... I'm not sure to what degree it tracks changes, but I initially copied in the original file, and then started making changes. Maybe it'll let you compare the first pasted version with the latest?

I can also just submit a PR for you to see the changes though, and then we edit in the hackmd once you see what the changes are.

Ah you're probably right. I keep forgetting hackmd has version history.

facepalm

Davidutro commented 5 years ago

Good edits.

The Is this for me section doesn't read well, is a bit awkward and clunky. Going to think about how to change it make it better.

Davidutro commented 5 years ago

@aburban90

List items don't need periods if they are phrases/not complete sentences To keep things consistent with the other landing pages I removed the periods in those lists.

aburban90 commented 5 years ago

@ghettodev seems like @Davidutro's view differs from what I understood we wanted?

Please confirm what our standard is

Davidutro commented 5 years ago

image

amy-jung commented 5 years ago

@Davidutro : PR ( awaiting review by @ghettodev ) covers some of the issues but needs another look by @aburban90

amy-jung commented 5 years ago

From @aburban90 : Possibly to add to style guide as resources:

aburban90 commented 5 years ago

@amy-jung slightly more in-depth descriptions... identical list

Add to Style Guide:

aburban90 commented 5 years ago

Are we going to do Style Guide with PR's? Seems cumbersome? Maybe have a HackMD? Toss it in as working doc in https://hackmd.io/WJ62RL67RJyiyx5kpgbipA?both

and pin to somewhere?

Davidutro commented 4 years ago

Closed, can be looked at for reference if needed.

Up to date issue can be found here:

387