search

symphonycms / docs.getsymphony.com

The official repository for the Symphony CMS documentation site
2 stars 2 forks source link

Contributing instructions on README #5

Closed bernardodiasc closed 9 years ago

bernardodiasc commented 9 years ago

Write in https://github.com/symphonycms/docs.getsymphony.com/blob/gh-pages/README.md#contribute informations about how to contribute.

In short:

Here we have the full list of pages https://github.com/symphonycms/docs.getsymphony.com/blob/gh-pages/_data/nav_docs.yml

Each have an id that need to be the same as the filename of the page file. And in the page file (markdown) also need to have an id variable that need to match.

This is just basics information to include new pages.

johnpuddephatt commented 9 years ago

I've added some draft content to a page on the wiki.

How to contribute

This needs checking, as it's only a draft. My thinking was that README.md could include the following info:

bernardodiasc commented 9 years ago

@johnpuddephatt very nice.

About the markdown parser, we are using RedCarpet, but was a random choice. Kramdom looks interesting too.

About the usage of the Wiki, I recomend to keep only for us while developing the docs. Let me explain, when you land in a repo at first time, the chances you digg info in the Wiki is very low. What I recomend instead is make the brief explanation in the README on how to edit/create pages, how to setup Jekyll + link, and more information link pointing to a page in the docs site. It will be 2 places to worry about instead 3. If further informations about contributions (for documentation) where in the docs site, people will end up reading with much higher chance, also considering people that land first in the site (instead the repo).

johnpuddephatt commented 9 years ago

we are using RedCarpet – apologies I didn't check, I just read Kramdown was the default for GH-Pages + Jekyll and assumed that's what was being used.

Regarding your other points, I'm fine with everything you've suggested, makes sense.

bernardodiasc commented 9 years ago

No worries about the markdown thing. :)

I am wondering about this "contributing" topic, I think we can make good use of this and expand to something wider. In the docs site can have a contributing section with informations about this, not only for the docs site, but for every symphony ecosystem.

When I started on symphony I was unsure how to help, even asking people its hard to find answers. Contributing section would have so articles about contributing rules, workflow, lead persons, feature requests (like "call for help")...

Well... just brainstorming here, dont need to be like that. Let's write a bit more and see what we get.

jonmifsud commented 9 years ago

@bernardodiasc having details about how to contribute is very helpful. The symphony ecosystem is not so 'simple' there's the core stuff, symphonists repo with the extensions. New extensions and putting them on symphonyextensions.com and contributing to the docs.

Oh and maybe how to organise a Symposium :) would love to do that if there's enough interest.

johnpuddephatt commented 9 years ago

This has just been mentioned over in the discussion about content structure #8. It's definitely something we need to factor into the content plan.

Presumably that would mean keeping the readme on here fairly minimal – just an explanation of what symphony/the documentation is, and a link to the 'how to contribute' page(s) on the docs site?

bernardodiasc commented 9 years ago

Presumably that would mean keeping the readme on here fairly minimal – just an explanation of what symphony/the documentation is, and a link to the 'how to contribute' page(s) on the docs site?

Perfect. Let's start applying our DRY rules :D

bernardodiasc commented 9 years ago

Worth to mention the Editorconfig setting. For consistency coding sake

bernardodiasc commented 9 years ago

One more thing to know about, GItHub offers a alert in PR in repos that have CONTRIBUTING.md file.

See https://github.com/blog/1184-contributing-guidelines

johnpuddephatt commented 9 years ago

:+1: we should add a CONTRIBUTING.md file...

bernardodiasc commented 9 years ago

README.md and CONTRIBUTING.md

Both very succinct (can be improved still, of course), let's focus on a better explanation in the Contribution section in the docs site.

I'm closing this, because the goal of this issue was about this two files. Now this subject is documentation content.

nitriques commented 9 years ago

CONTRIBUTING.md should also be added to the core project IMO. I'll open a new issue.