[haiku-doc] Report on the API Documentation Team Meeting of May 19th 2007
- From: "Niels Reedijk" <niels.reedijk@xxxxxxxxx>
- To: haiku-doc@xxxxxxxxxxxxx
- Date: Sat, 19 May 2007 12:13:52 +0200
Hi guys.
Below I've got the report. To read a nice hyperlinked markup version,
check out my blog at
http://haiku-os.org/blog/nielx/2007-05-19/report_on_the_api_documentation_team_meeting_of_may_19th_2007.
If there are any mistakes/omissions, please tell me.
Niels
---
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.
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.
Other related posts:
- » [haiku-doc] Report on the API Documentation Team Meeting of May 19th 2007
