[haiku-doc] Re: Some direction
- From: Tim Howe <timh@xxxxxxxxxxxxxxx>
- To: haiku-doc@xxxxxxxxxxxxx
- Date: Mon, 5 Oct 2009 15:47:51 -0700
On Mon, 5 Oct 2009 20:44:42 +0200
Niels Reedijk <niels.reedijk@xxxxxxxxx> wrote:
> Sample 1 is definitely not according to conventions used in API
> documentation (see GNOME/GLIB, Qt). So I would argue against using
> that (due to the duplication of 'This is').
I am actually fairly familiar with the Qt4 documentation and looked
through it a bit more when thinking about this. I have to agree this goes
against convention that I am familiar with.
> About the removal of capitals in these short descriptions: this
> seemingly makes sense in the overview (the table that lists all
> methods), however, these lines are reused in the detailed
> descriptions, where it is definitely not aesthetically pleasing to not
> have a capital letter. Now it would be entirely possible to not print
> the 'brief's in the detailed view, but this would mean that the brief
> always has to be reworded. Furthermore, the brief is brief for a
> reason, it happened to me more than once that I was browsing through a
> document (instead of merely clicking through from the main table) and
> the brief gives a concise description of the method so I know whether
> I could us it.
I see your point, and I think I agree. I was actually more worried
about creating confusion be removing punctuation, but I will leave these alone
where clarity is not obviously improved by changing them. My other concern is
that I am not sure what form is the best for the translators, but perhaps that
understanding will come when more of that is under way...
> I am interested in your grammatical and stylistic changes to the rest
> of the document, so if you could send a patch for those I want to
> review and commit those.
I think I have an intermediate version of the file that just contains
those changes. I will go through it again this evening and get it to the list.
> > Hopefully it doesn't seem like I am making a lot out of
> > nothing. I think if we establish the excepted style up front we'll be
> > better off later. I'm wanting to move forward with some confidence.
>
> I would rather hope you would try to keep the original guidelines and
> try to write new documentation, which is greatly needed. I can imagine
> the pleasures of setting guidelines and trying to define things before
> hand, but please realize that the existing guidelines are mainly a
> product of all the experimentation I did earlier. During the course of
> writing the documentation you will most probably gain some
> appreciation for the guidelines, as well as getting a firm
> understanding of the issues and then you can make a good argument in
> changing or updating the guidelines.
This is, of course, a goal of mine. I actually started looking into
this with the expectation of writing docs for the layout classes; I was playing
around with them and didn't see formal API docs. I will probably get to doing
that before long, but I really think I am benefiting by looking through
existing docs first (and from getting feedback), especially since I am new to
this kind of writing and to Doxygen. I figured as long as I was going to go
through them anyway, I may as well try to make my time useful to others =)
> I am much looking forward to seeing some of your work, I think my
> interest in the API documentation is renewed and I will start to do
> some work as well.
That's good news; I'm sure seeing your changes will be enlightening.
--TimH
Other related posts:
