Bug 35223 – Add a page on how to ask questions

• Status: RESOLVED
• Resolution: FIXED
• Component: WebKit Website

[Julien Chaffraix]

Following a lot of questions on the WebKit mailing lists that asked for some refinement, it is needed to get explain this to newcomers. This would avoid having to say the same stuff again and again.

[Julien Chaffraix]

Created attachment 49178 [details]
First try: Add such a page and tweak contact.html

[Julien Chaffraix]

Darin, as a regular contributor to the different mailing lists: could you comment on this patch? Maybe it could be worth getting more inputs on the webkit-dev mailing list?

Thanks!

[Darin Adler]

Comment on attachment 49178 [details]
First try: Add such a page and tweak contact.html

I started reviewing. Here are some comments on the first couple of sections.

> +<h1> How to ask questions about WebKit?</h1>

This phrase is not a question, so should not have a question mark. Or we could rephrase it as a question.

> +The following tips are for new members of any WebKit mailing list who want to get help on learning WebKit.
> +They are rules that goes beyond the WebKit mailing lists scope and are repeated here for clarity.

"rules that goes beyond" -> "rules that go beyond"

But also "rules that go beyond the WebKit mailing lists scope" is an unusual use of the word "scope". I would say:

"These can help you decide what mailing list to use and include advice on other ways to find answers and help that go beyond the mailing lists."

> +There is 2 ways to query the archives: using google or the <a href="http://dir.gmane.org/search.php?match=webkit">gmane archives</a>.

"There is 2 ways" -> "There are two ways"

"using google" -> "Doing a web search".

> +<br><br>

Formatting should use "<p>" elements for each paragraph rather than text separated by "<br>".

> +If you choose to use google, make sure you use "site:lists.webkit.org" in your query.<br>

Instead: 'You can limit a Google search to the mailing list archives by using "site:lists.webkit.org" in your query.'

[David Levin]

Comment on attachment 49178 [details]
First try: Add such a page and tweak contact.html

Darin's comments plus these.


> diff --git a/WebKitSite/asking_questions.html b/WebKitSite/asking_questions.html
> +<h2> Be precise </h2>
> +Give us as many details as possible. Generic questions will get generic answers.

Explain as many details as possible. Generic questions will likely not get a valuable response.


> +Also people are less likely to answer generic questions as they are not sure what the question really is.
> +
> +Make sure you include at least:</br>
> +<li> which port are you using: Apple, Windows, Chromium, Qt, Gtk, Wx, ...</li>

I think OSX or Mac is typically used instead of Apple.


> +Remember that we are not in your head so the most you give us, the easier it will be for us to help you.

Since we cannot read your mind, the more you give us, the easier it will be for us to help you.

> +(You can find the complete output here: http://foobar.com).<br><br>

This doesn't use pastebin.com as you suggested above.

> +
> +There are some questions that appears regularly on the mailing list. We have included the answers here for more convenience.

s/appears/appear/
s/more convenience/your convenience/

> +
> +<h3> Does WebKit supports Foo? </h3>
> +
> +The most reliable way to answer it is by looking at the source code. WebKit development is fast
> +pace, often the asked feature is already implemented although it has
paced. Often the requested feature is already implemented although it has


> +not been widely used yet. Bear in mind, sometimes the level of
> +supports between different ports are not the same (example: Apple port
s/are/is/

I don't think this example adds much with X as the feature.

> +has implemented feature X, but Qt port still does not have it).

> +The following links are also useful (note that they may be incorrect
> +or outdated):<br>

Do you need to tell people that it is incorrect or outdated?

> +<li><a href="http://en.wikipedia.org/wiki/Comparison_of_layout_engines_(HTML)">Wikipedia comparison of the layout engines: HTML support</a><br></li>
> +<li><a href="http://en.wikipedia.org/wiki/Comparison_of_layout_engines_(XML)">Wikpedia comparison of the layout engines: XML support</a><br></li>
> +<li><a href="http://en.wikipedia.org/wiki/Comparison_of_layout_engines_(Cascading_Style_Sheets)">Wikipedia comparison of the layout engines: CSS support</a><br></li>
> +<li><a href="http://en.wikipedia.org/wiki/Comparison_of_layout_engines_(Document_Object_Model)">Wikipedia comparision of the layout engines: DOM support</a><br></li>
> +<li><a href="http://en.wikipedia.org/wiki/Comparison_of_layout_engines_(HTML_5)">Wikipedia comparision of the layout engines: HTML5 support</a><br></li>
> +<li><a href="http://en.wikipedia.org/wiki/Comparison_of_layout_engines_(ECMAScript)">Wikipedia comparison of the layout engines: ECMAScript support</a><br></li>
> +<li><a href="http://en.wikipedia.org/wiki/Comparison_of_layout_engines_(Scalable_Vector_Graphics)">Wikipedia comparison of the layout engines: SVG support<br></li>
> +<li><a href="http://en.wikipedia.org/wiki/Comparison_of_layout_engines_(Non-standard_HTML)">Wikipedia comparison of the layout engines: non standard HTML support</a><br></li>
> +
> +<h3> I want to port WebKit to a new platform? </h3>

This isn't a question.

> +
> +As a starting point, check first <a href="http://trac.webkit.org/wiki/SuccessfulPortHowTo">the sucessful port how-page</a>.
s/how-page/how to page/

> +
> +Granted, it's not complete, feel free to contribute. Also, try to find a port similar to what you are targeting and use it
Try to find a port similar to what you are targeting and use it
> +as a basis, instead of writing everything from scratch.

as a basis, instead of writing everything from scratch. While doing your port, you may find that you wished the page had 
mentioned that fact.Please modify the page and add it.

> +
> +<h3> What the code flow is? </h3>
How does X work?

> +
> +The best answer is to fire your debugger. WebKit code move really fast - as we already said - and giving such an answer at one

The best way to answer this is to use your debugger. Set a break point where you want to investigate and get a stack trace. Then, you will
see which functions call your code.

> +
> +<h2> Things to remember when you ask a question </h2>
> +
> +<li> We offer our help on a voluntary basis, you can't expect us to be
s/you/but you/

> +100% at your disposal. Be patient, no need to insist on the urgency
s/Be patient, no/ Be patient. No/


> +<li> WebKit is a big project with a huge code base, you must be willing
s/, you/, so you/



> +<li>Last but least: there are often (negative) complaints that WebKit code
s/least:/least,/
s/(negative)//

> +is not easy to understand. Well, this is your chance to contribute! We
> +have started some helping pages on this, just check out:
> +<a href="http://trac.webkit.org/wiki/WikiStart#GettingAroundtheWebKitSourceCode">our wiki's page to get around the code</a></li>

s/get/getting/
s/around/around in/


> diff --git a/WebKitSite/contact.html b/WebKitSite/contact.html
> +<p><a href="http://lists.webkit.org/mailman/listinfo/webkit-dev">webkit-dev</a> is for discussion of the WebKit project's development per itself. If you do not intent to hack WebKit, you should direct your questions to webkit-help.</p>

s/hack/contribute patches to//

[Julien Chaffraix]

Created attachment 50794 [details]
Second try: Addressed David's and Darin's comments, tweaked the "keeping in touch" page to see the different mailing lists easily

This patch should address all your comments about the wording or the presentation.

[David Levin]

Comment on attachment 50794 [details]
Second try: Addressed David's and Darin's comments, tweaked the "keeping in touch" page to see the different mailing lists easily

Thanks! Just a few things to address. (I likely missed some items that could be better but my believe is that having this up is better than what we have now. Once it is visible if people see issues they can fix it then with small patches.)


> diff --git a/WebKitSite/asking_questions.html b/WebKitSite/asking_questions.html

> +<p>Granted, it's not complete, feel free to contribute. Try to find a port similar to what you are targeting and use it

s/complete, feel/complete, so feel/

> +<li> We offer our help on a voluntary basis so you can't expect us to be
> +100% at your disposal. Be patient. No need to insist on the urgency

s/the urgency or something similar./urgency./

> +or something similar. Asking urgently for an answer usually does not get you
> +the answer faster.</li>
> +
> +<li> We love to grow our community, and thus we like to help the

s/help the/help/

> +beginners. Afterall, every expert was a beginner at some point in his
s/Afterall/After all/
s/"his"/"his/her"/


> diff --git a/WebKitSite/contact.html b/WebKitSite/contact.html
> +<p>There is a number of mailing lists for WebKit related topics. Archives for all the lists as well as information on joining them are available on the individual list page. There is also a <a href="http://dir.gmane.org/">gmane archive</a> for some of the following mailing lists.</p>

There are a number of mailing lists
      ^^^

[Julien Chaffraix]

Committed in r56541 updated with David's comments.

Thanks for correcting my English!