Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a documentation contributors guide #2718

Merged
merged 2 commits into from
May 1, 2018

Conversation

benjaminwil
Copy link
Contributor

I tried to keep this short and sweet. This is a list of guidelines for anyone wanting to contribute documentation.

I don't expect all of these to get followed 100% of the time, but I think it is a useful resource nonetheless.

Copy link
Member

@tvdeyen tvdeyen left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All fine, just some thoughts about code blocks


- Do not abbreviate terminal commands. (`bundle exec rails server`, not `bundle
exec rails s`.)
- If your code is longer than one line or 20 characters, use a code block rather
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code should be in blocks if it’s longer than one word. Otherwise it may break the line and this isn’t really readable.

I would even consider to put code always in a block, so it stands out. Code inside paragraphs seldomly make sense. Only if you want to reference a variable or constant it makes sense. Also syntax highlighting only works for code blocks.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good call, thank you. Fixed.

Copy link
Member

@tvdeyen tvdeyen left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome. Thanks

Copy link
Member

@kennyadsl kennyadsl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 thanks @benjaminwil!

@tvdeyen tvdeyen merged commit 2e3f112 into solidusio:master May 1, 2018
@benjaminwil benjaminwil deleted the docs_contributing branch May 3, 2018 20:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants