Report on the API Documentation Team Meeting of May 19th 2007

This is a report of the meeting of the API documentation team that was held on May 18th 2007 at 19:00 GMT on freenode.org in the #haiku-doc channel. The full IRC log is hosted by John Drinkwater.

Here are some of the highlights for those that don't want to read the complete document. In this meeting people introduced themselves to the group. There was discussion on the working process, and it was decided to create a three phase working process and to start on the support kit. Communications will be done on the mailing list and on a wiki page. There were decisions on authors versus proofreaders and some small amendments to the existing API documentation guidelines were decided on.

Participants

• [Beta] - John Drinkwater
• AJS - Alan Smale
• ddew - David Weizades
• MauriceK - Maurice Kalinowski
• nielx - Niels Sascha Reedijk
• niklas
• sardaukar - Bruno Antunes
• Thom_Holwerda
• valexy - Alexey Veselovsky
• wd - Andrey Yakovlev
• wile_work - Mike

1. Introductions

All the participants introduce themselves. There is some chitchat on a variety of things. nielx apologizes for being late. nielx will lead the meeting.

2. Getting Started Information

nielx refers to the Getting Started document AJS wrote. He asks who has used this document and what the experiences were. Both sardaukar and ddew used that document to set up their environment in windows. They both claim that it is sufficient. Thom_Holwerda notes that it looks good and clear.

sardauker says that he misses some examples of good and bad documentation practises. AJS thinks that this subject belongs to the API documentation guidelines. nielx agrees.

Thom_Holwerda and niklas are on macs. nielx encourages them to try it out and send any amendments to the getting started document to AJS.

3. Tasks

nielx wants to find the most efficient way of getting the work done. He proposes to divide the work up in small tasks. These need to be done individually because of the nature of internet work, however, he wants to make the mailing list the 'hub' of the documentation efforts where issues and contributions can be discussed. There was a list of current open tasks, only the first two (proofread MIDI2 kit and support kit) are of importance.

At this point AJS reminds everyone in the room to subscribe to the mailing list.

sardauker thinks that there should be a probation period for anyone contributing to the documentation team before they should become a team member. nielx wants to know if we really want to form an 'official' team, differentiating between team members and contributors, or that we just want to be a collaboration of contributors. niklas is in favor for the official team structure, sardauker thinks time should dictate what will happen. This issue was not discussed further.

ddew asks if the team should be for 'regular' documentation as well. Thom_Holwerda says we should focus on the API part. nielx and niklas agree. However, nielx says that if someone comes up with a good plan on other forms of documentation, that he is willing to facilitate that person.

Then, niklas asked for a status report. nielx says that currently the support kit is documented, and the MIDI2 kit is documented, as well as the interface that drivers use if they want to communicate with the USB stack. The MIDI2 kit is written by Matthijs Hollemans, who was the developer of that kit, but it does not adhere to the API documentation guidelines, and it is informal here and there. It should be rewritten. The support kit was documented while nielx was drafting up the API documentation guidelines, which means that some parts may be outdated and not adhere fully to those guidelines. AJS proposes to start on one thing and then branch out. niklas offers to start on the MIDI2 kit, because he has some knowledge of the protocol. nielx proposes to first start with the support kit, which is relatively simple, to give everyone a good introduction into documenting API's.

The working process was decided after a long discussion. In short, it was proposed to see documenting the API as a three phase process. The first phase is where someone writes the documentation from scratch. The second phase is proofreading to check whether or not the technical details are correct, and if the document follows the guidelines. This is the 'rewording' phase. The third phase is when the grammar mafia goes over the document to iron out any remaining kinks. sardauker proposes a two stage commit policy, where two people need to both have gone over a document to make sure all the stages were performed, but AJS says that he doesn't think it's bad to have unpolished documentation in the repository. The task can alwas be done later. Thom_Holwerda reasserts that proofreading should not be done by the author. sardauker thinks there should be a WIKI page to keep track of who is doing what. nielx will create that page on Trac's WIKI, but he asserts that any claim should be made on the mailing list first, and edited on the WIKI. In case of confusion, the mailing list has precedence over the WIKI. [Beta] thinks there should be an expiry date on claims of two weeks after the claim. nielx agrees, but wants to change that 'rule' to two weeks after the last sign of life on the mailing list.

The issue of language standard was brought up by Thom_Holwerda, he wanted to know whether to use American English or British English. It was decided to use American English, since the API was written in American English.

4. API Guidelines

We started off with the point stated by sardauker, who wanted to have a few examples of good and bad documentation, and the reasons for it. He suggests a WIKI. nielx and AJS think it will be best to encounter those examples during the early work on the support kit, and post them on a wiki.

Then the API guidelines came up. nielx wanted to know if there are any issues with it now. The general impression was that they were considered quite straightforward.

There were a few issues or amendments to discuss. The first was one from Axel Dörfler, who for the sake of consistency wanted to replace 'Documented By' in the header with 'Authors'. There was some discussion on the naming, on whether or not it would be clear that the mentioned authors were of the document and not of the source (it was decided it was), and whether or not proofreaders could be considered authors. It was decided to use the terms 'Authors' and 'Proofreaders' in the header for future work.

Then there was a discussion on the criteria on when someone is a proofreader and when he is an author. Thom_Holwerda asked if there should be a distinction between technical proofreaders and grammatical proofreaders. ddew also wondered when proofreading turned into authoring. nielx proposed to let people decide for themselves. As soon as they thought they did some massive rewording, they could put themselves under the 'Authors' heading, else they could be 'Proofreaders'. He wanted to leave responsibility to whoever does the patch. This was agreed upon.

Last point was an amendment to the guidelines to state that code examples in the documentation should follow the coding guidelines as much as possible. This change was accepted.

Two more complicated issues nielx wanted to bring up, will be posted on the mailing list.

5. Conclusion

At the end e-mailaddresses and instant messaging contacts were exchanged.

nielx will perform the following tasks:

1. Write a summary of this meeting.
2. Create a wiki page that contains the status for the support kit.
3. Ask Waldemar which guidelines/restrictions apply for using the wiki.

There was a short discussion for another meeting in the future, but no decisions were made.