Doc Consistency aka Standards about symfony-cmf-docs HOT 9 CLOSED

hi @wouterj,
thanks a lot for your interest! i really appreciate your offer and think it would be a good think to have. i will point to this issue on the cmf mailinglist symfony-cmf-devs so others can vote concerns if they have any.
so far we just did not pay close attention to the doc standards, it was no delibarate decision to not follow those standards. imo this is an additional issue we have to take into account when going over the doc (i planned to review large parts to streamline them and work on the consistency of the content. might as well also fix coding consistency while i am at it. or if you would want to do it, please don't do it this weekend, or we will get an annoying conflict mess :-)

from symfony-cmf-docs.

we absolutely want to follow the standards. let's try to get it fixed ASAP, while keeping an eye on open PRs so that we do not create hard typo resolve conflicts.

from symfony-cmf-docs.

@dbu and @lsmith77 thanks for you response! I'm currently reading the getting started chapters. I'm fixing bugs in the format and other inconsistencies while I'm reading it.

There is another commonly used thing in your documentation: Inline hyperlinks vs reference hyperlinks. In the symfony docs, we use this:

A sentence with `some link`_ [...]

At the end of the document:

.. _`some link`: http://symfony.com/

In the CMF docs, this is used:

A sentence with `some link <http://symfony.com/>`_

It's not something we included in our standards, because people already used it. I think we (you) have to decide which one you would use. Both have some pros and cons.

from symfony-cmf-docs.

great, be sure to do a pull request soon so we see where it goes :-)

regarding the links, i prefer the inline links much more readable when writing the doc. we rarely link the same thing twice with the same label which i guess is one of the use cases (besides avoiding long urls in the middle of the doc). but in the end we should do the same as the symfony doc does to be consistent. if that means having the links at the end of the document, lets change.

maybe you could do a PR to add that convention to the doc standard to see if people in symfony agree?

from symfony-cmf-docs.

@dbu I've created a WIP PR: #112

I will create a PR for the symfony docs this weekend.

from symfony-cmf-docs.

Great idea @wouterj, I think it's very good of you to do the reviews.

I will try and contribute some more docs (even if just small tweaks) soon. Will I need to do anything different when submitting a PR?

from symfony-cmf-docs.

with wouter re-reading the doc and fixing the format, we should all be careful to have the latest version of this repository and quickly do the pull request, rather than keeping local changes for a few days. otherwise we risk running into merge conflicts. note that i also intend to restructure some of the documentation to streamline it, this will again create potential for merge problems (splitting files and such is not something git takes easily :-)

so lets PR fast, merge fast and when doing something also quickly check if open PR could affect what we do.

apart from that, i guess we should all read the symfony doc part on how to write doc, or wouter will tell point out errors to us that we will have to fix ;-)

from symfony-cmf-docs.

All good points, I think I might also post an outline on the mailing list before any big changes. Best to know what I'm talking about before writing docs. ;)

from symfony-cmf-docs.

i guess we can close this one?

from symfony-cmf-docs.