Maciej
On 15 June 2014 21:26, Maciej Sobaczewski <sobak@php.net> wrote:
First of all, I need some linguistic support. My English level is poor and
any help on making it less broken is aprecciated.
Great work... and your English level is a lot better than you think it
is, it reads like it was written by a native English speaker :-)
Because I am an annoying pedant, though, I cannot resist the urge to
point out that it is spelled "appreciated". A C that makes an S sound
when spoken is always single. A reasonable rule of thumb (although
it's English so I'm sure there are many exceptions because we like to
make things difficult) is that any word that begins with an "ap" sound
will be spelled with a double P, unless the P is followed by another
hard consonant. A notable exception to this rule is a number of words
beginning with "appl" - maybe it not such a great rule or thumb :-(
On a more on-topic note...
On 15 June 2014 21:26, Maciej Sobaczewski <sobak@php.net> wrote:
Technical backend, so parsing files and integrating it with doc.php.net, is
also not ready yet, but I will commit it soon. It should be simple work.
Is the plan for this to render this as HTML and publish it on
doc.php.net when we are happy to "release" it? I fully support the
motion to unify this information into one place and burn the rest, but
I would like to suggest that it be published on wiki.php.net
(obviously doc.php.net can link to it). The main reason for this is
that it will make it easier to contribute - anyone who has anything
useful to add will already have a php.net account and so will already
have the necessary permissions to edit it. Running it through git
makes the system a lot more complex and runs the risk of becoming yet
another repo with people attempting to contribute but trivial PRs sit
outstanding for weeks/months at a time.
The aim is to simplify, my vote would be to adhere to KISS on this as
much as possible.
Thoughts?
Hello Chris,
firstly, thank you for kind words, I really... appreciate it ;) I will probably remember proper spelling of that word thanks to your detailed explanation.
When it comes to target place to store this tutorial. You said that main goal is keeping it simple to contribute. As far as I know every member of doc team, so everyone who has access to phpdoc, has karma to write web-doc also.
I decided to put it in this repo because I think that our wiki syntax is awful. Markdown is very popular now and IMO it increases chance of new contributions. And I just really like it :) Also, I don't think that there's a big risk of abandoned PRs since we have working mailing list notifications. Sure, git is way more complicated than wiki, but it might be useful when we would like to keep this document versioned. Wiki provides diffs but it's not VCS. I think that is good to use real versioning system, when we have to keep this tutorial up-to-date and track changes carefully.
Regards,
Maciej.