Just a few random thoughts sprinkled below. trey On Jul 18, 2005, at 1:19 AM, David Storey wrote:
In the absence of any opinions, I'll list a few ideas of my own. If there is any pressing need for any documentation, or anyone has any ideas, then give me a shout.
Developer Documentation:
I would start calling this something like "Web Site Developer Doc", as opposed to the next section, which is for both Application developers (people writing an app using WebKit) and WebKit developers (people adding to or changing WebKit). In theory each group is interested in its level of doc and that of the proceeding groups.
I think for each technology that WebKit supports (HTML, XHTML, XML, CSS etc.), there should be a page that mentions:
What the technology is What problems it solves/it's reason for being Each tag in the standard (for tag based technologies) Each attribute for the tag
For each tag and attribute it should:
Describe what it does Show an example of it used correctly Mention if it has been depreciated (for example tags that can't be used in strict mode for html) Say if WebKit either implements it, implements it with known bugs (link to bugzilla bugs?), doesn't support it, or wont support it, possibly for each version of WebKit.
As well as the W3C standards, other none standards could be listed in their own sections such as IE, Mozilla and WhatWG extensions.
I would make the goal to be emphasizing how WebKit differs from the published standards for each of these technologies, and the defacto standard of MS IE (and possibly other browsers). There are 1000 places someone can read what each HTML tag does and how to use it (in fact linking to one of these might be good). The primary value to be added here is not yet another complete CSS document, but how WebKit extends or differs from what people expect in these standards. In fact, the more you replicate existing standards doc, the more it dilutes those key differences. (Part of my assumption in that comment is that we are resource limited in terms of creating this doc.)
Project Documentation
See my first comment about the title/purpose for this. I guess the "project" aspect of this applies to the group hacking on WebKit itself, but not Web Site or App developers.
I'm not too sure about API docs and tutorials, as I don't program in C or obj-c, but I'm sure there are plenty of Apple api documents that can be linked to. I've seen a number of one line of code browser tutorials on the likes of MacDevCenter that could also be linked too. Some more documentation could be written to cover common tasks that developers would use WebKit for, for example, to display a web feedback or registration form in an application.
There could be a document giving an overview of the differences between KHTML/KJS and WebKIt as well as a family tree of what WebKit is based on, and what projects are based on WebKit (GTK+ WebCore, GNUStep WebCore etc.).
I think the first thing would be a block diagram of the major pieces (WebKit, WebCore, KHTML, KWQ, JavaScriptCore, KJS) and how they plug into an OS X environment (relationship to Safari, Cocoa, Darwin). For comparison it would be nice to have the same picture for the Konq/ KDE scenario.
It would be nice if there were pages for each sub project -- as exists now -- that mentions what the aims of them projects are. The pages should have some way to add discussion about how it is planned to move them forward, and what will be implemented and how. Maybe the talkback feature of the wiki could be used for this. It would be a good way to find out what features people really want to see in WebKit. Perhaps a roadmap could be produced.
For standards that are not supported by safari (PICS, P3P?), there could be a page assessing them and whether they may be supported in the future. If a standard is still in the review stage, any points that are unclear or need refining could be mentioned, so that they could be discussed.
HeaderDoc could possibly be used for creating API documentation from the source code. Coming from a Java background, I've always found JavaDoc useful, and if WebCore and JavaScriptCore used it then i might make it easier for coders, that don't know the code well, to find the part of the code that they want to work on, and help spotlight index the source better. This would make big changes between the WebKit source and the KHTML/KJS however unless they rolled in the comments too.
Maybe a list of frequently asked questions and frequently submitted bugs/none-bugs would be nice.
Links to all the test suits and what each test is for would be nice, along with whether the current version of WebKit passes or fails the test, so that it is easy to find ones that fail.
Website:
Probably not a priority, but the site could maybe get it's own style instead of the safari rss theme that it has at the moment. A logo would be nice, as the current image shows the Safari icon, even though WebKit is used outside of Safari (it may also be a copyright issue if a developer wants to show a badge to say their app is webkit enabled?). I'm not sure if Apple has logos for the Kits, but don't the Core frameworks have them funny gem sphere things? It can't harm having our own Hexley mascot in Bermuda shorts and on a surfboard too ;)
On the wiki I added a page for apps that currently used WebKit. I'm not sure what Apple apps use WebKit, so maybe someone could add the ones I've missed and any others they know of. I filled in the Team members page too, but I took the information from bugzilla, so there are members missing. If you are missing or any info is wrong then you can add yourself or change it.
I think that's all for now,
thanks,
David
On 7 Jul 2005, at 19:19, John Sullivan wrote:
I think using Bugzilla to submit proposed changes to the main site seems sensible. There are a few of us with opendarwin commit privileges who can do the actual website changes. The reviewer for the proposed changes would depend on the topic, to ensure technical accuracy.
I don't have any opinion on how the documentation should be improved, but I know others do, so hopefully they will chime in.
John _______________________________________________ webkit-dev mailing list webkit-dev@opendarwin.org http://www.opendarwin.org/mailman/listinfo/webkit-dev