DOC Update contributing docs page #367
Conversation
9328138 to
0c72781
Compare
There was a problem hiding this comment.
Removed anything that mentioned translations. While the docs are set up in a way that could theoretically handle translations, I really don't think we'd accept a translation of the docs as it would be impossible to keep up to date without someone dedicated to doing so.
| Modifying documentation requires basic knowledge of [PHPDoc](http://en.wikipedia.org/wiki/PHPDoc) and | ||
| [Markdown](http://daringfireball.net/projects/markdown/) as well as a GitHub user account. | ||
| Modifying documentation requires basic knowledge of [markdown](https://www.markdownguide.org/). Our documentation also includes some additional syntax which you can read about in the [extended markdown syntax](#extended-markdown-syntax) section below. |
There was a problem hiding this comment.
- I'm removing phpdocs from this page - that belongs in the contributing code page.
- The old markdown link doesn't show any of the extended syntax like fenced code blocks or tables which we take advantage of.
|
|
||
| [warning] | ||
| If you submit a new feature or an API change, we strongly recommend and request that you include a PR to update the necessary documentation. This helps prevent our documentation from getting out of date. |
There was a problem hiding this comment.
This doesn't belong here - it's mentioned in the contributing code section which is where people will be reading if they're submitting a new feature or an API change.
| ## What to write | ||
| After editing the documentation, click "Commit changes", then describe your changes in the "commit summary" and "extended description" fields below. | ||
|
|
||
| See [what to write (jacobian.org)](http://jacobian.org/writing/great-documentation/what-to-write/) for an excellent introduction to the different types of documentation. Also see [producing OSS: "documentation"](http://producingoss.com/en/getting-started.html#documentation) for good rules of thumb | ||
| for documenting open source software. |
There was a problem hiding this comment.
What to write? Write documentation. These links were just adding more (and frankly outdated) burden to anyone trying to contribute.
| ## Structure | ||
| Click "Propose changes" when you are ready to commit your changes. This saves them to the forked repository on your profile. | ||
|
|
||
| * Keep documentation lines shorter than 120 characters. | ||
| * Don't duplicate: Search for existing places to put your documentation. Do you really require a new page, or just a new paragraph of text somewhere? | ||
| * Use PHPDoc in source code: Leave low level technical documentation to code comments within PHP, in [PHPDoc](http://en.wikipedia.org/wiki/PHPDoc) format. | ||
| * API and developer guides are two forms of source code documentation that complement each other. | ||
| * API documentation should provide context, ie, the "bigger picture", by referring to developer guides inside your PHPDoc. | ||
| * Make your documentation easy to find: Documentation is useful only when it is interlinked so please make sure your contribution doesn't become an inaccessible island. At the very least, put a link to your index page in the same folder. A link to your page can also appear | ||
| as "related content" on other resource (e.g. `/tutorials/site_search` might link to `/developer_guides/forms/introduction`). |
There was a problem hiding this comment.
I've moved any relevant points to the style section.
Most of this is outdated IA stuff. We're going to have to redo our IA eventually as it's currently a mess and is really hard to find relevant documentation (in part because some of these suggestions simply didn't scale well).
In the meantime, I can't see anyone adding substantial enough docs to need this part of the guide.
| * API documentation should provide context, ie, the "bigger picture", by referring to developer guides inside your PHPDoc. | ||
| * Make your documentation easy to find: Documentation is useful only when it is interlinked so please make sure your contribution doesn't become an inaccessible island. At the very least, put a link to your index page in the same folder. A link to your page can also appear | ||
| as "related content" on other resource (e.g. `/tutorials/site_search` might link to `/developer_guides/forms/introduction`). | ||
| You will see a form to submit a Pull Request. Make sure to target your pull request at the correct branch you took note of earlier. |
There was a problem hiding this comment.
| You will see a form to submit a Pull Request. Make sure to target your pull request at the correct branch you took note of earlier. | |
| You will see a form to submit a pull request. Make sure to target your pull request at the correct branch you took note of earlier. |
| * Do not put a `$` in front of lines of bash code examples. | ||
| * When referencing directories, always add a trailing slash to avoid confusions with regular files | ||
| * "Silverstripe CMS" is used to refer to the Silverstripe CMS open source project as a whole. | ||
| * "Silverstripe" is used to refer to the company, where appropriate. |
There was a problem hiding this comment.
| * "Silverstripe" is used to refer to the company, where appropriate. | |
| * "Silverstripe Ltd" is used to refer to the company, where appropriate. |
There was a problem hiding this comment.
We've been actively avoiding "Silverstripe Ltd" to refer to the company as per @maxime-rainville's instruction
Personally I agree that the Ltd suffix avoids confusion, but 🤷♀️
0c72781 to
6921725
Compare
Issue