search

yearn / yearn-docs

Old Documentation gitbook for yearn. Replaced by https://github.com/yearn/yearn-devdocs
GNU General Public License v3.0
98 stars 134 forks source link

Contributor's Guide: Writing Style Guide #98

Closed Faolain closed 3 years ago

Faolain commented 3 years ago

Ticket related to https://github.com/iearn-finance/docs/issues/85 as a prerequisite.

Document: Writing Style Guide: https://hackmd.io/dXQecpkJQX6XRy4y7k7j3g

Motivation: Standardize Yearn documentation language for consistency and to ease comprehensibility.

Rationale: Inconsistent language can make it hard for newcomers to the Yearn ecosystem understand how Yearn products work and how to contribute to the community.

Faolain commented 3 years ago

Apologies for the tag @dudesahn (hopefully I got the right one haha). I know you've been working on Naming Conventions & Standards, the above doc has a space for that in order to standardize/formalize any future documentation. Whenever you get a chance feel free to add it into that section or add/edit/remove anything you feel seems right :)

dudesahn commented 3 years ago

Yes! I think I'm the only one who has this name anywhere haha. Once we get everything finalized (we're so close!) I can update these docs as well, thanks for pointing me in the right direction.

dudesahn commented 3 years ago

@Faolain how does this work? Do I just update the hackMD document and then you'll update the relevant .md file?

dudesahn commented 3 years ago

I'm pretty much doing a brain dump for that section right now. It may not all be relevant to this part of the docs, but I wanted to get it down on paper and then we could move it to the right place after.

Faolain commented 3 years ago

Perfect thanks so much @dudesahn! Yeah that works we can always edit if need be. And yep I'll submit a PR once a review is done.

dudesahn commented 3 years ago

@Faolain I ended up removing some of the more in-depth naming convention formulation stuff to a separate document here: https://hackmd.io/PzIRsKmMQ-CLrMhkvblYKg. I can always add it back if need be, but I don't think it belongs in with the rest of the writing style guide. What I removed was more technical, such as how to design the smart contracts name and symbol fields. Just let me know what you think.

Faolain commented 3 years ago

No worries at all I think that makes sense, we can always add a link to "Learn More ". Really appreciate it!

definn-farmer commented 3 years ago

I've just made a comment about replacing the Naming Convention content for the published link, to avoid duplicates. Otherwise looks great to me.

Faolain commented 3 years ago

PR submitted https://github.com/iearn-finance/yearn-docs/pull/132