info/learnxinyminutes-docs
1
0
Fork 0
mirror of https://github.com/adambard/learnxinyminutes-docs.git synced 2025-01-17 21:49:22 +01:00
Code Issues Releases Wiki Activity

Merge pull request #1753 from onebree/contrib

Browse Source 
Add contributing-specific file
This commit is contained in:
Adam Bard 2016-02-16 10:38:34 -08:00
commit 6be4227736
2 changed files with 100 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
CONTRIBUTING.markdown Normal file
View File

@ -0,0 +1,70 @@
# Contributing
All contributions are welcome, from the tiniest typo to a brand new article.
Translations in all languages are welcome (or, for that matter, original
articles in any language). Send a pull request or open an issue any time of day
or night.
**Please prepend the tag `[language/lang-code]` to your issues and pull
requests.** For example, `[python/en]` for English Python. This will help
everyone pick out things they care about.
We're happy for any contribution in any form, but if you're making more than one
major change (i.e. translations for two different languages) it would be super
cool of you to make a separate pull request for each one so that someone can
review them more effectively and/or individually.
## Style Guidelines
- **Keep lines of under 80 chars**
+ Try to keep **line length in code blocks to 80 characters or fewer**.
+ Otherwise, the text will overflow and look odd.
- **Prefer example to exposition**
+ Try to use as few words as possible.
+ Code examples are preferred over exposition in all cases.
- **Eschew surplusage**
+ We welcome newcomers, but the target audience for this site is programmers
with some experience.
+ Try to avoid explaining basic concepts except for those specific to the
language in question.
+ Keep articles succinct and scannable. We all know how to use Google here.
- **Use UTF-8**
+ For translations (or EN articles with non-ASCII characters) please make sure
your file is UTF-8 encoded.
+ Try to leave out the byte-order-mark at the start of the file. (`:set nobomb`
in Vim)
### Header configuration
The actual site uses Middleman to generate HTML files from these Markdown ones.
Middleman, or at least the custom scripts underpinning the site, requires that
some key information be defined in the header.
The following fields are necessary for English articles about programming
languages:
- **language** The *programming language* in question
- **contributors** A list of [author, URL] lists to credit
Other fields:
- **filename**: The filename for this article's code. It will be fetched, mashed
together, and made downloadable.
+ For non-English articles, *filename* should have a language-specific
suffix.
- **lang**: For translations, the human language this article is in. For
categorization, mostly.
Here's an example header for an Esperanto translation of Ruby:
```yaml
---
language: ruby
filename: learnruby-epo.ruby
contributors:
- ["Doktor Esperanto", "http://example.com/"]
- ["Someone else", "http://someoneelseswebsite.com/"]
lang: ep-ep
---
```

103
README.markdown
View File

@ -1,88 +1,45 @@
# [Learn X in Y minutes](http://learnxinyminutes.com) # [Learn X in Y minutes][1]
Whirlwind tours of (several, hopefully many someday) popular and Whirlwind tours of (several, hopefully many someday) popular and
ought-to-be-more-popular programming languages, presented as valid, ought-to-be-more-popular programming languages, presented as valid, commented
commented code and explained as they go. code and explained as they go.
## We need YOU!... ## We need YOU!...
... to write more inline code tutorials. Just grab an existing file from ... to write more inline code tutorials. Just grab an existing file from this
this repo and copy the formatting (don't worry, it's all very simple). repo and copy the formatting (don't worry, it's all very simple). Make a new
Make a new file, send a pull request, and if it passes muster I'll get it up pronto. file, send a pull request, and if it passes muster I'll get it up pronto.
Remember to fill in the "contributors" fields so you get credited Remember to fill in the "contributors" fields so you get credited properly!
properly!
## Contributing ## Contributing
All contributions are welcome, from the tiniest typo to a brand new article. Translations All contributions are welcome, from the tiniest typo to a brand new article.
in all languages are welcome (or, for that matter, original articles in any language). Translations in all languages are welcome (or, for that matter, original
Send a pull request or open an issue any time of day or night. articles in any language). Send a pull request or open an issue any time of day
or night.
**Please tag your issues and pull requests with [language/lang-code] at the beginning** **Please prepend the tag `[language/lang-code]` to your issues and pull
**(e.g. [python/en] for English Python).** This will help everyone pick out things they requests.** For example, `[python/en]` for English Python. This will help
care about. everyone pick out things they care about.
We're happy for any contribution in any form, but if you're making more than one major change We're happy for any contribution in any form, but if you're making more than one
(i.e. translations for two different languages) it would be super cool of you to make a major change (i.e. translations for two different languages) it would be super
separate pull request for each one so that someone can review them more effectively and/or cool of you to make a separate pull request for each one so that someone can
individually. review them more effectively and/or individually.
### Style Guidelines For a detailed style guide, please review the full [CONTRIBUTING][2] guidelines.
* **Keep lines under 80 chars**
* **Prefer example to exposition**
* **Eschew surplusage**
* **Use UTF-8**
Long version:
* Try to keep **line length in code blocks to 80 characters or fewer**, or they'll overflow
and look odd.
* Try to use as few words as possible. Code examples are preferred over exposition in all cases.
* We welcome newcomers, but the target audience for this site is programmers with some experience.
So, try to avoid explaining basic concepts except for those specific to the language in question,
to keep articles succinct and scannable. We all know how to use Google here.
* For translations (or English articles with non-ASCII characters), please make sure your file is
UTF-8 encoded, and try to leave out the byte-order-mark at the start of the file. (`:set nobomb` in Vim)
### Header configuration
The actual site uses Middleman to generate HTML files from these Markdown ones. Middleman, or at least
the custom scripts underpinning the site, requires that some key information be defined in the header.
The following fields are necessary for English articles about programming languages:
* **language** The *programming language* in question
* **contributors** A list of [author, URL] lists to credit
Other fields:
* **filename**: The filename for this article's code. It will be fetched, mashed together, and made downloadable.
For non-English articles, *filename* should have a language-specific suffix.
* **lang**: For translations, the human language this article is in. For categorization, mostly.
Here's an example header for an Esperanto translation of Ruby:
```yaml
---
language: ruby
filename: learnruby-epo.ruby
contributors:
- ["Doktor Esperanto", "http://example.com/"]
- ["Someone else", "http://someoneelseswebsite.com/"]
lang: ep-ep
---
```
## License ## License
Contributors retain copyright to their work, and can request removal at any time. Contributors retain copyright to their work, and can request removal at any
By uploading a doc here, you agree to publish your work under the default time. By uploading a doc here, you agree to publish your work under the default
[Creative Commons Attribution-ShareAlike 3.0 Unported](http://creativecommons.org/licenses/by-sa/3.0/deed.en_US) [Creative Commons Attribution-ShareAlike 3.0 Unported][3] licensing included on
licensing included on each doc page. each doc page.
Anything not covered by the above -- basically, this README -- you can use Anything not covered by the above -- basically, this README -- you can use as
as you wish, I guess. you wish, I guess.
[1]: http://learnxinyminutes.com
[2]: /CONTRIBUTING.markdown
[3]: http://creativecommons.org/licenses/by-sa/3.0/deed.en_US