[webkit-dev] Documentation project

[Trey Matteson]

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 at opendarwin.org
> http://www.opendarwin.org/mailman/listinfo/webkit-dev
>
>