Development Tools • 40:32
The Darwin Documentation Project provides HowTos, Man pages, and HeaderDoc comments for Darwin projects. Find out how to contribute to Darwin documentation using DocBook, XML, and HeaderDoc. Learn how HeaderDoc makes it easy for all Mac OS X developers to maintain updated documentation for C and C++ code.
Speakers: Ron Hayden, Matt Morse
Unlisted on Apple Developer site
Transcript
This transcript was generated using Whisper, it has known transcription errors. We are working on an improved version.
So the Darwin Documentation Project was launched a few months ago. When we launched Darwin a couple of years ago, we made a major leap into open source. With the Documentation Project, we made another major leap because we recognized that the documentation is as important as the source code. And just like the source code, it's got to be open. There have to be resources and tools out there for you to contribute. And you have to see what we at Apple are doing. So this presentation will give you the lowdown on everything that's going on.
It's going to cover what's changing in documentation. So we've learned a lot from open source. It's changing how we're doing documentation. You may learn a few things about why documentation hasn't always worked the way you wanted in the past and why it's getting better now. I'm going to go over with HeaderDoC HowTo and the Man pages the areas of documentation that the project covers. And then we're going to get into some detail on what documentation do we have related to Darwin. What documentation are we working on and where are some great areas for you to contribute if you happen to have some knowledge.
One big question we get is, well, what does the Darwin Documentation Project cover? Darwin Documentation covers what Darwin covers, and probably most people in this room are aware of what that is, but here's a quick summary. Obviously, that's the Mach BSD kernel, kernel extensions, system framework, command line environment, network services.
Now, one of the things that people notice is that our Apple writers, the people contributing to the Darwin Documentation Project, are primarily focusing on drivers and some basic kernel stuff. Some people in the community want some other things. We'll get into some opportunities there for people in the community to contribute and such, but I can say right up front that our focus is definitely drivers and the core kernel information that you need right now.
So, as I mentioned, you've probably been the recipient of problems in the traditional documentation process, meaning once you get the documentation, it's not complete or it's really late, it comes out way out to the product. Why does that happen? Well, here's the traditional model for documentation. And it starts with the engineer. The engineer has the information that you need. And they may write that down. They may write comments in the header file. They may meet with a writer and tell them what that information is. The writer gets that information. They put it together into a nice document.
They get it reviewed. They send it to the editor. The editor goes through it for consistency, grammar, and makes sure that they're communicating clearly, works with them on those things. Then it goes to the production department. The production department goes through every page of the documentation. They make sure it's paginated correctly. They make the art look good. They make sure that we're following the right template.
It then goes out to the vendors and distribution, where it gets printed up into a book. It goes out into the bookstores. Finally, it gets to you. This whole process has taken anywhere from six to nine months. Now, you open the book. And let's say you find a bug or a feature missing that you want to document it, and you communicate that back to the engineer.
Six to nine months later, if you're lucky, when the book comes out, the information that you requested is in there. Or maybe it's not. Maybe we didn't have time to get to it. So this is the source, and even though this is a circle, this is kind of a waterfall that I'm communicating here, this is the source of many problems and many of the reasons that the documentation doesn't meet your expectations.
We have to follow this sometimes. There are some books for which this is the best model. Large conceptual books like the IOCAP Fundamentals book that we'll talk about later, which need to discuss the whole architecture from top to bottom, provide lots of illustrations, get lots and lots of review to make sure that we're communicating it exactly right. They've got to go through this process. But, you know, you read that book once and the rest of the time you're reading the rest of the documentation. And it doesn't need to go through that process.
Great. We have a broken slide. Okay. We get together, the TechPub's managers get together about once a year in an offsite and talk about what is going right, what's going wrong, or what we could do better, and what we could learn from our industry. And a year or two ago, it was my job to present what we could learn from the rest of our industry. And we sat there and scratched our heads for a while and realized not a whole lot at this point.
We were, Apple is actually in a position of being really leading edge in the industry in terms of our public methodology and what we're doing. But we knew that there was a lot more we could do. And after some research, what I discovered was that there was an area of the software industry that we had a lot to learn from. And that was the open source area.
And they bring a new model to documentation because the open source projects, when they created documentation projects, it was engineers who created those projects. Engineers come from a code background. They believe that things should be buildable in a source repository that anyone should be able to contribute, and they should be diffable. These are all brand new concepts to us in publications.
So the model, we'll see what happens with these slides here, the model in... The Darwin Documentation Project is a production team that provides tools for the development of the C code. and Matt Morse are the main developers of the project. They are the developers on the project, or even subject area experts who just know a lot about it and have a lot to communicate.
Finally, you have the audience, which is right now in Darwin primarily developers. This will also be, of course, sysadmin and users over time. One of the things to notice is that developers on the content providing side, developers on the audience side. So these people need the tools to talk to themselves.
With the open source tools and using repositories and such, we cut down on the waterfall model. Instead of having necessarily an editor in the process, it will maybe just go to the tool and then go to the audience. Or in the ideal case, and HeaderDoC, which we'll talk about in a moment, is an example of this. In the ideal case, the production people provide the tool and get out of the picture.
So in the case of HeaderDoC, we give you HeaderDoC, the developers have HeaderDoC, it goes directly to the audience when they release their product or their header. The audience can comment on that, the developer can re-release it right away, or even better, this is what's happened with Darwin, we had IOGraphicsLib.h in the I/O Kit.
We hadn't gotten around to getting HeaderDoC into that yet. But Tori Lyons, a Darwin developer, noticed this, and he put together the HeaderDoC and sent it to us. So in this new model, things are so different from the old one that the audience is now providing the documentation to the developers.
This is very exciting to us, and this is where we're focusing all of our energies. So let's talk about what I call the ideal model there, and that's HeaderDoC. HeaderDoC treats the documentation as source code. The documentation resides in the header files in a tagged format. HeaderDoC currently covers C and C++ projects. It's very similar to JavaDoc tags. And I'd like to have Matt Morse come up and show us a HeaderDoC file. And if we could go to... So this is a HeaderDoC file.
And notice in addition to regular comments, we have right at the top a header-wide comment. This is so that you can provide some documentation related to the entire framework or header that you're dealing with. But then most of the comments are on a per function or type def or data type basis. So if we go down to IOFB create cursor, create shared cursor there, you can see this is a-- so this is a function declaration and the HeaderDoc related to it. And the thing to notice-- and I'll provide some detail over here.
First thing to notice is that it has a special comment format. And that is /*bang. Some people have asked us why we did that, why we didn't either use the Java doc comment format or just a normal comment, which would just be /*. The reason we went this way was because, first of all, while we designed HeaderDoc to be very similar to Java, we wanted to make sure that we were using the same Java doc as the Java doc. It's not Java doc.
And it has to use different tags because of C and C++. So we didn't want to confuse any Java doc processing tools and have them try to grab this comment and do something with it. Second, though, we didn't want to look like a regular comment because sometimes, as you can see here, the HeaderDoc balloons up the size of the header. We were concerned that some engineers would not want that to be the case in their published headers. Actually, so far, people don't really seem to have an issue with it.
But just in case, we wanted them to be able to run a tool before they published a header which would strip out the HeaderDoc files but leave the normal comments so they could leave in comments like don't pass null to this and such and not have those stripped out of the file. So that's why we have this comment format. There's only one required tag for a HeaderDoc comment. And that's the first tag, which explains what it is. So in this case, it's a function, IOFB create shared cursor.
There are a variety of different tags depending on what you might be identifying. The rest of the tags are optional. A great one to have is an abstract. The abstract will get pulled out of some of our tools and used in tables of contents so people can see quickly what it is they're going to jump to. Then, of course, the meat of the comment is the discussion. This is typically one to three paragraphs of your information about what this function does.
Then for one or more of the parameters, however many you choose, you can provide parameter specific documentation. Finally, if you have a return code, you can choose to identify what that return code is. The only other requirement for a HeaderDoc comment is that its placement must be directly above the thing that it's talking about. There can be white space and all that, but it has to be above so that when our Perl tools go through and process this, they can connect the two together and make use of them.
So now I'd like to have Matt walk through the actual process of creating some HeaderDoc here. Okay, we can build HeaderDoc either directly in Project Builder, and I'll show you how to do that, but more commonly, especially for Darwin developers, you'd be building it from the command line because you don't have Project Builder to use.
The command is quite simple. It's headerdoc to HTML. And that's in user bin on your system. You can give it an output directory to drop the documentation into. -o is for the output directory. And then you tell it what to process. And what to process can be either a single header, a group of headers, or a folder.
And if it's a folder, it'll recurse through the folder, finding all headers and processing them. In this case, before we run this, let's take a look. We've got iographicslib.h, as we were talking about, but we have a number of other headers here, too. There are eight headers, one's in a subfolder. So we process it.
It's gone through the eight headers. It emits a comment for each one that it visits. Here you notice that it's skipping one because it didn't find anything of interest to document. There were no HeaderDoC comments in that header. And I know because I counted, it's gone through eight headers and it's produced over 50 pages of documentation. So let's look at that documentation.
So we produce this folder, doc, and here are the seven folders of documentation, one per header, that we've generated. And we can look at iographics lib documentation. It produces a frame set of documentation, so you can open the index.html to get there. And as you can see, you've got a TOC on the left, and that at header comment that Ron pointed out has become the opening page of your documentation. For each function, you have a link, and you can see how those tags have been converted into HTML. The function tag, let's look at the one that Ron pointed out, the create shared cursor. We have the title. That was the at tag.
The function tag. Abstract is here. The declaration is pulled directly from the header. And then we have the tag. This is the discussion block. And then each parameter is listed and described in this table. And the result code follows. So you have a long page of each of the functions. In the TOC, you'll see grouping headings depending on the type of API, enumerations, and pound defines.
And so you can print out this documentation, which would be hard to do with a frame set. There's a link at the bottom that will open up one continuous page of documentation, and then you can print that out. It has all the functions, all the enumerations, and so on.
Okay, now that's nice that we've created a folder of documentation for every header, but it would be even more convenient if there was a way to gather this all together in a more easily navigatable arrangement. And so we have another script, GatherHeaderDoc. That takes as its input the folder to go visit. It visits every island of documentation that Headerdoc created and it creates a TOC and also adjusts some links so that you can get from the island back to the TOC and from the TOC to the island. So let's look at what that looks like.
Okay, so here's our documentation. Notice that now we have this master TOC. A lot of the names of the files are configurable through a configuration file that I'll talk about later. So if we open that, You see the links to each of the pools of documentation. And we've added a top button here to get back to the TOC.
Now, if one of these headers, let's say-- Let's say, event source. If it described more than just C API, if it had a C++ class, you end up with more than one frame set of documentation. This is the frame set for the header itself. And in fact, there's only one thing other than the class of interest in it, and that's that #define. But there's also a class, ioEventSource. So we can go visit that.
And notice that this is much like the C frameset, except now you have member functions and member data. And within each of those headings, you have the access type, public, private, and so on. And your class documentation is there for you. So I told you that you can build this documentation directly in Project Builder. I'll show you how that's done.
If you've been to any of the Project Builder talks, you know that they're build phases for your targets. So if you go to the Targets tab and look at-- this is just an empty project that contains my header files. And look at the build phases. You'll see down here I've added two more. These are shell script build phases.
And all that does is run a script. And here I define it. And this is pretty much exactly what I ran on the command line. The only difference is I'm using some symbolic constants that Project Builder knows about to tell it where to find the source and where to put the documentation.
So I'm going to look for the source headers in the project source and I'm going to put the documentation in the resources folder inside the app wrapper. And after I do that, I'm going to run the second shell script, GatherHeaderDoc, which will go into that folder of documentation and create the master TOC. So let's do that.
Now if you look up here in the build pane, after it does the normal build phases, you'll see running by the HeaderDoC comments. I think we're about there. OK. That was HeaderDoC going by. There's GatherHeaderDoC. So if we go back to the files display and look in the products now we have our application HeaderDoc demo dot app and you can go in there we have created this folder of documentation and here's our master TOC. And as you saw in some of the Project Builder talks, we're trying to integrate the documentation with Project Builder. So in a later release, you'll be able to see your documentation right there.
So one last thing I'd like to show is the documentation for HeaderDoC. It is installed on your system. It's in Developer Documentation, Developer Tools, and it comes with HeaderDoC if you download it from our website as well. HeaderDoC has reference to tell you pretty much what I've just told you about how to use it and what to expect from it, how to run it. It also talks about the configuration file I mentioned that lets you set some of the names of the files. And then it starts discussing how to tag your source.
And at the bottom here, there's a reference for all the tags that you can use in C and C++. So if you're wondering about function tags, well, here are the tags that you can use at function, at param, at result. And for every type of API, it gives an example of a declaration that's been tagged.
And for those of you who would like to contribute to the HeaderDoC effort and want to play with Perl, it's a fairly nicely structured script, I think, that has a parser that generates objects. It's an object-oriented Perl script, and this is the class hierarchy of the objects that are produced. The source code itself has a lot of comments, and there's an active mailing list that you can sign up for to join the effort. So I hope you use it. Thank you.
Thanks, Matt. And Matt is the primary author of HeaderDoC. If we could go to slides on both screens. So our goals for HeaderDoC. All C and C++ API in Darwin should be using HeaderDoC. If you own or are maintaining or contributing to a C or C++ project, start using HeaderDoC today if you're not already. We will then have a universal approach to reference across the system and it'll be the best for everyone.
We really want to support Objective-C, of course. We have, at each step, added functionality to HeaderDoC based on what we needed at that moment. As Cocoa becomes a reality on 10, we're very interested in adding Objective-C. A number of our people in the Darwin community have expressed interest in doing this.
Matt's a really busy guy right now and he's actually doing the code also to put the editing, the documentation viewing and editing into Project Builder. So we're not going to get Objective-C. We're going to be in for a little while and if you're someone who knows or would like to learn Perl and is interested in that, you could really help us out.
Join the mailing list. You can go to list.apple.com or to the Darwin site and find out about the mailing list. And finally, Matt showed how you can do this in Mac OS X and Project Builder. We want to make a push button so that you don't have to go and add in your own build phase stuff. That will happen in the near future.
Next we have, as an area that we cover in the Darwin Documentation Project, are how-to documents. So these are different from HeaderDoc in that who provides them tends to be different. In HeaderDoc, it's almost always the engineer who created the code who provides the HeaderDoc. With how-to documents, anyone who has the knowledge can and is encouraged to provide a how-to document.
These are typically self-contained small articles from 1 to 10 pages. There's no particular restriction. You can make it as long as you want. But you can make it as long as you want. So you can make it as long as you want. That's the standard. They solve a particular problem or tell you how to get your job done in a particular aspect of the system.
We'll get into some examples later of what we have and some of the ones that would be useful to add. They're authored in DocBook XML. A lot of people have heard about XML, maybe they've used it a bit for their system, but they haven't necessarily seen how it was intended to be used originally. We can go into that and how we use it.
DocBook XML Is the industry standard XML definition for technical publications? So the idea with XML is that each industry would come up with its own set of tags specific to that industry. The medical industry is doing this for billing, etc. Well, probably the most advanced set of XML tags in the world is DocBook for exactly the kind of stuff that we do.
XML is structured information, which we will get to in a minute. And there is-- if you are interested in trying to venture into XML and learn what this is all about, there's a lot of information in the Darwin documentation HowTo in the HowTo site. The only problem there is that the tools for XML, the editing tools for XML, aren't quite there yet. If you remember with HTML, it took two or three years before there were good HTML editors. And XML is much harder to create an editor for.
So there are lots of editors in progress, but there aren't any that are going to solve all your problems. And we're more interested in getting the information. If you have a HowTo in you, if you have information that other Darwin developers or system administrators or users should know about, we just want the information.
So if you don't want to get into XML or if you venture into it and find it's a little murky, just go ahead and email to me your document or to the Darwin developer list. We will turn it into XML for you and add it to the project.
So let's get into some of the detail of XML and how it's different from HTML, which you may be familiar with. HTML has formatting-based tags. So your tag will say, this word is italic, this word is bold, this word is an H1. But it won't say why it's italic. It won't say why it's bold. So processing tools can't do anything with it. They can't change the formatting based on the output or do anything with it.
XML is exactly the opposite. It only tells about the content of the tags. It does not say what to do with it. So for instance, in a Darwin Documentation HowTo, you have a title of the document. The title is clearly named "Title." You have a first name of the author.
You have the email address of the author. So absolutely nothing is said about how to process this. That comes later. Other tools will come along, take a look at these and process them, and we'll show you how that works. This is a very important difference. It takes people a little while to get used to. The effect is to turn your document into a mini database. The other very important aspects of XML, and really, in my opinion, the reason that XML is taking off in the world, are that the tags are hierarchical and closed.
Now, HTML has a little of both of these. The problem is it's not strict about it, so it doesn't help very much. So, for instance, a paragraph tag in HTML does not have to be closed. Some browsers make you close list items, some don't. And so you don't know how your document is going to work in different browsers until you just try it. In XML, this never happens. There's an absolute rule.
Tags must be closed. So to take a reasonably sophisticated little block of XML from a HowTo document, the revision history. So there's a revision history section. Each revision gets a comment and such. This has an opening tag, rev history, and a closing tag, rev history. Everything else will be inside there.
Each revision has an opening revision tag and a closing revision tag. Then, for each piece of information about that revision, it has an opening tag and a closing tag. So we have the revision number, we have the date of the revision, and finally, any comment we want to create for this revision. So this is a great example of how a tool goes through this and figures out what to do with it. The writer doesn't say anything, but here's the information that I'm providing to you.
One of the things people find when they hit DocBook is DocBook is a very mature set of XML tags and it tries to do everything. So you can create facts with DocBook, you can create books, you can create articles, you can create lots of other things. And that means there are so many tags that people get overwhelmed and they don't know what to do. The trick is ignore them.
You only need, in order to author a Darwin documentation HowTo document, to know about 10 tags. Now to be honest, at the top and bottom of the document there are a few more tags in that, like the Rev History there. You just want to copy those from the template that we give you on the site.
And don't worry, just fill in the information. You don't need to remember the tags or anything. The only tags you actually need to know when you're providing information are about 10. This is a good sample of them. So what a section is, a title, a paragraph. A couple different kinds of lists.
How to list code. And URLs. That's about all you need to know. So really, you just grab our template that we have on the site. That gives you all the tags you need to know. You don't need to worry about any of the others. Now I'd like to have Matt come up again and show us a demo of this.
Okay, so Ron talked about the nested nature of XML. Here's a document. This is the Darwin doc HowTo document. This is a document that describes how to create these HowTo documents. And as he mentioned, here's that revision history block and other standard blocks like the abstract. Something that's more like what you would be doing is these section blocks.
This is the facts section. We'll see this once we generate the HTML question and answer. It has a title and a paragraph and a section indicator. Okay, just as with HeaderDoC, you can build the stuff in Project Builder, but it's more likely that you'll be doing this on the command line.
The command that we use is XSLTproc, which is a-- A command that applies an XSL file to the XML file. The XSL file provides the formatting. Actually, it's more than that. It's a transformations file that takes the XML that is just defined in terms of semantics. This is a title, or this is an email address, and applies format to it. Beyond that, it can do other transformations, and we'll see that. The one that we're using is DocBook.
We're going to process the Darwin HowTo and redirect the output to a file. It will be HTML by the time this is done. We can open that HowTo file. Okay, so this is that XML now transformed into HTML. And things like the title are just applied, formats applied to them.
But things like the email address, the transformation is to create a mail-to link as well as to format it in a specific way. And then our input XML document did not have a table of contents. This was extracted by XSL Tproc and the XSL transformation file by looking at the structure of the document and extracting the upper and lower level headings and making them into links.
Also, we've got URLs that are now hot. And here's this question and answer section that we're looking at the titles, the questions, and the formatted answers. Also, if you go back up and show the revision history section, I wanted to stress something here. Oh, right. Yeah. So just wanted to stress here, here are the revision history tags that the writer provided. Here is the output.
As you can see, the XSL tool has done something completely different with them. It's created a sophisticated table. If you've ever done your own table editing in HTML, you know it's quite a pain. In this case, the writer didn't even know it was going to be a table. And there you have it. So that's the great power of using this process. OK, thank you.
Can we go back to slides on both, please? So our goals for HowTo documents. Well, we started the HeaderDoC project quite a while ago, and that's going very well. All of I/O Kit is in HeaderDoC, and many other projects are beginning to do that. Many other companies throughout the software industry, even totally unrelated to Darwin, are beginning to use HeaderDoC because they-- I mean, yeah, HeaderDoC-- because they find it to be a really valuable tool. HowTo documents, we just got going in the last couple of months.
Our goal is to document all common tasks. So anyone coming to Darwin to help develop it, administrate it, whatever, has a place to go, and find a quick explanation of the various things they need to know. So a great example of this is-- and it's up there now-- HowToBuildDarwin. We will have, next week, going up, HowToBeADarwinDeveloper.
We also, and this is really important to us, want to cover all the common driver families. So we'd like to have a HowTo for each driver family you can go to that gives you the lowdown on what you should be subclassing and what you need to expect when you're working with that. Finally, very important to the community and important to Apple too, is that there are a lot of topics that our writers at Apple are not necessarily the best people to provide information for.
And we're all really excited to see that Darwin is up on Intel, that a huge number of people have downloaded it for Intel. But to be absolutely honest, those of us sitting in Apple offices are not necessarily the best to provide you information on how to use it on Intel. So this is a great opportunity for people in the community to provide information for those Darwin users who need it.
And we'd love to see some of this. So if there's anything you know like that, that'd be great to contribute. Finally, we have our last section of documentation, the Darwin Documentation. That's man pages. As if you've done any development whatsoever on a Unix system, you know man pages are critical for Darwin development. If you've done any development on our system, you know man pages are maybe not in the state that we would like to be them in right now. So this is a major focus for the next couple of months for us.
And what we're working on is, of course, we want to have a complete set of accurate and useful man pages. And how we're getting there is, a few years ago, it made sense. At the time, to take the man pages and put them into a documentation project that a writer would maintain. And we ended up separating them in the code from the projects that they were documenting.
This turns out maybe not to, at least at this point, have been such a great idea. And the result is we have some stagnant man pages that need a lot of updating. And the engineers have kind of gotten out of the habit of keeping their own man page up to date.
So we need to explode this project, get the man pages back next to their commands where they belong. Get them back to their original state. Get the engineers updating them. We need to clean up a lot of old bugs. We really need to get back into staying in sync with our upstream man pages. So we need, in particular, to be working closely with the BSD people. Get the BSD, free BSD man pages in there and get that cleaned up. And that's, so again, the next couple of months, a major focus for us. And you'll be seeing that.
That's something we primarily, we will be providing some goals and guidelines for people doing their own commands on how to keep up a man page. But the rest of that's primarily something we need to do. We need to do at Apple. On Mac OS X, we're going to provide HTML display of the man pages in Project Builder along with the rest of the documentation. We're also considering, and this is something we'd like to get input on, maybe during the Q&A or if you send email or anything.
We're considering doing like OpenBSD and some of the others and putting up on the Darwin site a full HTML version of the man pages that you can search and navigate through. And where that goes on our priority list depends on how much people want it. We're not totally sure.
So now we get to what might be really interesting for some of you. What actual documentation do we have at this point? First of all, you should be aware that at this time there's two sort of places to go when you're dealing with Darwin-related information. One, of course, is the Darwin site. The other, though, is the ADC Mac OS X website where we have a whole kernel page of information that you may or may not be aware of.
This includes pointers to Iocat HeaderDoc, Iocat Tutorials, Conceptual Docs, etc. In fact, as of this week, this is a great thing to go and check out, we have the first part of our Iocat Fundamentals book explaining the whole system. We have brand new information about USB and HID up on the website, and that's a great place to check it out.
We have HowTo documents. So the Darwin developer, how to be a Darwin developer will get up next week. Building Darwin is there now. Some general ones like setting your Intel screen resolution. And then of course the Darwin Documentation HowTo, which contains quite a lot of information on all the stuff we're talking about today, tools you can use, what you need to know, etc. We are working on, we have tutorials now, kernel and I/O Kit and packaging and such tutorials. We're doing a revision of these to include versioning information. These should be up in the next week or two.
What we're working on. Well, as you can see, we're starting to bridge the gap between Darwin and Mac OS X in terms of this information. So we're no longer thinking of IOCit documentation and such as separate from Darwin. It's documenting Darwin technologies. Now, an important point there, though, is this doesn't mean that everyone has to be a Darwin developer or go to the Darwin site to get our information. This is how we're developing the doc.
This is how we're making our processes available, letting people have more information about what we're doing. When we distribute IOCit documentation or anything else like that, it will go to all the standard places. It will go to the standard developer CDs and up on the website and all the normal places, et cetera. So the Darwin process is just an opportunity for us to let you get closer to the documentation, see what we're doing, and contribute if you want to. We're doing the IOCit Fundamentals book that I've mentioned a couple times. It's a really critical book.
Go and check out the first part of it. We're going to be getting this up as rapidly as we can to give you the whole picture of the IOCit. And written by Terry Donahue, it's the same person who did the system overview book for Mac OS X that you saw a year or two ago. So we know it's going to be really good. And in addition to more cookbooks, of course, we're continually working on more HeaderDoC coverage.
This is what we like to call open source opportunities. You might also call it, it's not there yet. So this is all stuff we'll get to someday, but we would love it if people who know as much or more than we do in the community could contribute in these areas. So please, if you're someone who has information in kernel programming or debugging, architecture, VFS, kernel extension, network kernel extensions, make a note of it.
Think about doing a HowTo. Contact us. Email the Darwin Developer List. Email me. And of course, HeaderDoC coverage in your own projects. And if you see, as Tori did, HeaderDoC missing in something that you know a lot about, and you could spend an hour and provide it and help everyone else out a lot, that would be really great.
So if you don't know the stuff on that list, but you'd like to contribute, join the Darwin Developer List. We don't have a special documentation list at this point, because we want everyone to feel included. So join the Darwin Development List. Ask what people need. See what people are talking about. See if there's something that you can contribute to.
Write a HowTo document. And in particular, as I said, if you need to, just send me the HTML, the RTF, whatever it is. I'll turn it into XML for you. So on any issue related to the Darwin Documentation Project, you can contact me or send email to the Darwin Developers List for HeaderDoC and such. You can contact Matt even better. Send email to the HeaderDoC Developers Mailing List, which you can also join.