Comments (9)
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.
Related Issues (20)
- Update versions on symfony.com HOT 2
- Update Quick Tour to not use empty SE HOT 1
- make-homepage.rst HOT 4
- update quick tour to work with current version HOT 1
- 'DOWNLOAD AS PDF' link not working HOT 7
- simplify cmf documentation like core documentation HOT 3
- Document the SonataAdminIntegrationBundle HOT 1
- Move all sonata admin docs to the SonataAdminIntegrationBundle docs HOT 1
- Review all bundle docs
- Throughly review Quick Tour HOT 4
- Throughly review the Tutorial HOT 4
- Mention abandoned packages in their documentation HOT 2
- resource rest bundle
- Installation instructions conflicts with later database creation instructions
- [Seo] Explain the default usage of Sitemap
- Review Quick Tour HOT 1
- Integrate the book into the bundle docs
- Error in cmf_routing_auto.yml example HOT 1
- CreatePHP website redirect to porn website
- Link to spam site from main page HOT 8
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from symfony-cmf-docs.