Re: Tutorial - request for feedback

Hi Maciej On 16 June 2014 16:04, Maciej Sobaczewski <sobak@php.net> wrote: >> 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. I agree 100% on the wiki syntax vs. markdown in terms of which one is nicer to work with, this is a very valid point. I'm not sure that VCS provides enough benefit over what the wiki does in terms of version control for what would be required here. Overall though, along the KISS lines, I think that being able to use markdown probably trumps the wiki ease of access, so I'm happy to stick with doc.php.net for now - as long as the processes that deal with rendering and publishing etc are also thoroughly and publicly documented :-) Maybe if wiki can be updated so it understands markdown we can revist this? Although I certainly don't see that happening in the near future. Thanks, Chris