[webkit-dev] Documentation project

[David Storey]

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 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.

Project Documentation

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.).

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