Standards organization overhaul + convert to Markdown #19

rstevens-nerdery · 2018-04-11T20:09:16Z

I felt that the standards weren't very useful to me in the format they were in, and it didn't match up with a lot of other community-provided standards documentation in Ruby or outside it. I took some notes from https://github.com/thenerdery/html-css-standards, removed Jekyll, and updated it so that you can browse the standards within GitHub itself. I think this change will make it easier to contribute to and expand/organize the standards in the future.

Feel free to take as much or as little of this PR as you'd like to.

Changelog

Removed Jekyll structure, replaced with Markdown files viewable within GitHub repo
Reorganized structure of standards document into separate files
Added TOC with links to each file into README.md
Added detail to Rails best practices and moved primer on MVC/installation to a separate section
Added/updated sections: Ruby best practices (code quality, debugging tools), source control, testing best practices (still empty ... for now)

To easily see what the repository would look like, take a look at the markdown branch.

…structions

…ndards

…classes/non MVC code

n8rzz · 2018-04-12T13:14:10Z

standards/rails.md

+### Javascript
+
+* Use Javascript, not Coffeescript
+* Use Yarn to load Javascript libraries in Rails 5


Why yarn? Since [email protected], there is very little difference between npm and yarn. Npm comes with Node, so enforcing yarn effectively equates to mandating an additional project dependency.

It may be beneficial to also call out how to install node. Using Brew is not the best way, instead, a node version manager like nvm is the better option (for the same reasons rvm is a better way to install Ruby)

Woah, I didn't realize npm had improved so much. I'll see about updating this.

Npm has improved, but, is still significantly slower than yarn according to the sources I've found.

That being said, I do believe we can recommend tools, but mandating them should be left for situations in which they improve the workflow significantly for the entire discipline. Yarn vs npm probably doesn't make a significant difference in overall workflow, but, I welcome information telling me otherwise. :)

Just for my two cents, specifically in regards to npm vs yarn.

For a while (in js timescale) yarn was the absolute winner; faster installs, a .lock file, etc. But, that was sooo last year. Today, the two are really pretty close: https://medium.com/netscape/npm-5-yarn-killer-ba69737b24d0.

My argument with Yarn vs Npm is threefold:

Yarn adds another dependency

It doesn't really provide much extra value over npm

If you know the difference between yarn and npm, you probably already know what you're doing and can make your own decisions.

Ultimately, I agree with you @powder, mandating tools belongs in the context of a project.

faxanadu · 2018-04-12T13:49:11Z

Thanks for reorganizing it, that helps a lot already.

powder

First, thank you for taking the time to do this, I feel like it's a huge improvement already.

Second, I have left a few of comments, and I don't know if you rewrote the entire thing or just copied a lot of it and move some of the things around, but, I do feel like this PR is a good place to at least point out some of the places we have for improvement and or future thoughts. I don't think there's anything that prevents it from being merged and updated though.

powder · 2018-04-12T15:59:14Z

README.md


-There's two ways you can contribute to this repository:
+Today at The Nerdery, the Ruby discipline is effectively the Ruby on Rails discipline. We do not do much pure Ruby work and we do not do Sinatra work. Thus, the focus of this document is not actually Ruby standards, but instead Ruby on Rails standards.


While this does adequately portray what we're doing, I think this can be left as self-evident. There's nothing saying we will never have other work, or projects/clients that demand a different solution than rails. I don't know that pushing the thought that we're only capable of one thing is healthy for the discipline. We would want anyone that reads this document to know that we are Ruby engineers and promote ourselves as capable of providing a variety of solutions.

Maybe we can shorten this, or clarify that the standards we're documenting do tend to focus more towards Rails practices at the moment. It's good to have scope and we can expand it later.

powder · 2018-04-12T16:04:10Z

standards/deployment.md

@@ -0,0 +1,14 @@
+# <a name="deployment"></a>Deployment
+
+There are really 2 primary ways to handle deployment on Rails projects at The Nerdery:


A comment on writing style, feel free to ignore if you disagree.

Would this be better worded as 'There are two preferred ways' instead of 'There are really 2 primary ways'?

powder · 2018-04-12T16:05:01Z

standards/documentation.md

@@ -0,0 +1,65 @@
+# <a name="documentation"></a>Documentation
+
+Good documentation makes a long-lived project easier to understand and maintain. It can help introduce new developers to an unfamiliar codebase, or serve as a reference point for the team coming back to code 6 months later. Documentation may also cover important architectural decisions, complex business logic, or quirks and workarounds of the tech we're working with. Just as we put effort into making tests that last to ensure our application is stable and robust, we also focus on providing meaningful documentation.


powder · 2018-04-12T16:05:23Z

standards/documentation.md

+
+Good documentation makes a long-lived project easier to understand and maintain. It can help introduce new developers to an unfamiliar codebase, or serve as a reference point for the team coming back to code 6 months later. Documentation may also cover important architectural decisions, complex business logic, or quirks and workarounds of the tech we're working with. Just as we put effort into making tests that last to ensure our application is stable and robust, we also focus on providing meaningful documentation.
+
+A great article on improving Rails-based documentation published by Aaron Sumner can be found here. Many of the practices described below are pulled from his philosophy.


I think there's a missing link you intended to have here?

powder · 2018-04-12T16:06:13Z

standards/documentation.md

+
+## Write clear documentation
+
+* __Don't assume knowledge of the business__: If you've been working in the application for awhile, the names you've given your classes and methods may seem obvious, but to a newcomer they can be a large hurdle to overcome. Help explain ___why___ things are called what they are.


powder · 2018-04-12T16:12:27Z

standards/documentation.md

+#### __DON'T__
+* Use YARD based [reference tags](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md#Reference_Tags). Although this methodology reduces DRY documentation it also enforces coupling.
+* Overload your documentation. Having overly cumbersome documentation is just as bad as having no documentation at all. Keep your docblocks small, concise, and to the point. Often throughout the RubyDocs and YARD documentation pages you will be presented with large docblocks filled with markdown and html structures, unless this type of documentation adds significant understandability to the class or method we ask that you refrain from emulating this. "Short, Sweet, To The Point"
+* Don't create [custom tags](http://www.rubydoc.info/gems/yard/file/docs/Tags.md#Adding_Custom_Tags) unless absolutely vital to the understandability of the documentation. If you are presented with a case where you do need to make them ensure that you are always namespacing them.


Not specfically aimed at this line.

Do we want to add examples of some of the documentation standards to this document? Perhaps how/if we should document the keys inside of hashes, or not? It's not actually part of the Yard docs, but, I've seen some recommended suggestions on it and such things.

powder · 2018-04-12T16:12:56Z

standards/learning-resources.md

+1. [Ruby Warrior](https://www.bloc.io/ruby-warrior/) - a game for learning Ruby.
+1. [Rails Best Practices](http://rails-bestpractices.com/) - for learning a *right* way.
+1. [Rails Guides](http://guides.rubyonrails.org/) - the ultimate API document for figuring Rails out.
+1. [Ruby Koans](http://rubykoans.com/) - learn the quirks of Ruby by fixing unit tests.


Can we add Exercism? I'm a bit of a fan.

powder · 2018-04-12T16:14:07Z

standards/learning-resources.md

+
+We work in a company with lots of different disciplines all commingling on a regular basis.  PHP, .NET, Java, Rails and Python...  we all get along pretty well.  We're also quite adaptable and end up going where the work is - which might not necessarily be in our favorite discipline.  The most common frustrations I see developers thrown into the Rails world is that of not having started from a good base.
+
+You see, Ruby is pretty popular.  You might not know it, but a metric ton of the critical tools you use daily are built upon it.  For the most part, unless you're running Windows, Ruby is already installed.  ***gasp*** it was that easy?


Can likely add sources to back this. I like to point out that Ruby was recently reintroduced to the top 10 programming languages, and even the top 20 actually means it has somewhat significant usage in the world.

powder · 2018-04-12T16:16:01Z

standards/learning-resources.md

+  libxslt-dev libpq-dev libreadline-dev libyaml-dev libcurl4-openssl-dev \
+  postgresql postgresql-server-dev-9.1 git nodejs
+
+# Install RVM to properly select Ruby versions


Is there a specific reason we settled on RVM? Is this kind of a legacy decision just handed forward?

I ask out of ignorance, please educate me.

powder · 2018-04-12T16:18:33Z

standards/ruby.md

@@ -0,0 +1,46 @@
+# <a href="#ruby"></a>Ruby Best Practices


👍 to this entire file, while there may be exceptions, i do believe a lot of these tools significantly aid quality development.

rstevens-nerdery added 17 commits February 22, 2018 20:50

Add CHANGELOG.md

2b74c14

Update .gitignore

03821af

Remove Jekyll structure (use Markdown only)

390bb21

Add CONTRIBUTING.md

cb8a5d8

Update README.md - Add TOC, add overview and goasl, remove defunct in…

f869fd9

…structions

Add standards folder; Move learning resources from index.md into /sta…

87e1031

…ndards

Split the rest of index.md up into different sections

df28802

Update ruby standards with code quality gems + remove fluff

0b58e95

Add debugging tooling section to ruby.md

7ce02fc

Move installing Rails to learning resources section

a6824c2

Nest headers in Rails standards

c499545

Reword branching strategies section

c61e024

Move MVC primer out of main Rails specs + add more detail on service …

995ee34

…classes/non MVC code

Expand Rails standards and clean code basics

463aaa4

Remove unused ruby tooling header

e9bc07f

Updating links in TOC

7b61f52

Add stubbed out testing section

d1e1f7d

rstevens-nerdery added the enhancement label Apr 11, 2018

n8rzz reviewed Apr 12, 2018

View reviewed changes

powder reviewed Apr 12, 2018

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Standards organization overhaul + convert to Markdown #19

Standards organization overhaul + convert to Markdown #19

rstevens-nerdery commented Apr 11, 2018 •

edited

Loading

n8rzz Apr 12, 2018

rstevens-nerdery Apr 12, 2018

powder Apr 12, 2018

n8rzz Apr 12, 2018

faxanadu commented Apr 12, 2018

powder left a comment

powder Apr 12, 2018

powder Apr 12, 2018

powder Apr 12, 2018 •

edited

Loading

powder Apr 12, 2018

powder Apr 12, 2018

powder Apr 12, 2018

powder Apr 12, 2018

powder Apr 12, 2018

powder Apr 12, 2018

powder Apr 12, 2018 •

edited

Loading


		There's two ways you can contribute to this repository:
		Today at The Nerdery, the Ruby discipline is effectively the Ruby on Rails discipline. We do not do much pure Ruby work and we do not do Sinatra work. Thus, the focus of this document is not actually Ruby standards, but instead Ruby on Rails standards.

		@@ -0,0 +1,14 @@
		# <a name="deployment"></a>Deployment

		There are really 2 primary ways to handle deployment on Rails projects at The Nerdery:

		@@ -0,0 +1,65 @@
		# <a name="documentation"></a>Documentation

		Good documentation makes a long-lived project easier to understand and maintain. It can help introduce new developers to an unfamiliar codebase, or serve as a reference point for the team coming back to code 6 months later. Documentation may also cover important architectural decisions, complex business logic, or quirks and workarounds of the tech we're working with. Just as we put effort into making tests that last to ensure our application is stable and robust, we also focus on providing meaningful documentation.


		Good documentation makes a long-lived project easier to understand and maintain. It can help introduce new developers to an unfamiliar codebase, or serve as a reference point for the team coming back to code 6 months later. Documentation may also cover important architectural decisions, complex business logic, or quirks and workarounds of the tech we're working with. Just as we put effort into making tests that last to ensure our application is stable and robust, we also focus on providing meaningful documentation.

		A great article on improving Rails-based documentation published by Aaron Sumner can be found here. Many of the practices described below are pulled from his philosophy.


		## Write clear documentation

		* __Don't assume knowledge of the business__: If you've been working in the application for awhile, the names you've given your classes and methods may seem obvious, but to a newcomer they can be a large hurdle to overcome. Help explain ___why___ things are called what they are.


		We work in a company with lots of different disciplines all commingling on a regular basis. PHP, .NET, Java, Rails and Python... we all get along pretty well. We're also quite adaptable and end up going where the work is - which might not necessarily be in our favorite discipline. The most common frustrations I see developers thrown into the Rails world is that of not having started from a good base.

		You see, Ruby is pretty popular. You might not know it, but a metric ton of the critical tools you use daily are built upon it. For the most part, unless you're running Windows, Ruby is already installed. *gasp* it was that easy?

Standards organization overhaul + convert to Markdown #19

Are you sure you want to change the base?

Standards organization overhaul + convert to Markdown #19

Conversation

rstevens-nerdery commented Apr 11, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

faxanadu commented Apr 12, 2018

powder left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

powder Apr 12, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

powder Apr 12, 2018 • edited Loading

Choose a reason for hiding this comment

rstevens-nerdery commented Apr 11, 2018 •

edited

Loading

powder Apr 12, 2018 •

edited

Loading

powder Apr 12, 2018 •

edited

Loading