[haiku-doc] Re: Pahe III BlockCache.dox .diff
- From: "Alan Smale" <ajsmale@xxxxxxxxx>
- To: haiku-doc@xxxxxxxxxxxxx
- Date: Mon, 28 May 2007 18:16:00 +0100
On 28/05/07, Niels Reedijk <niels.reedijk@xxxxxxxxx> wrote:
Hi Alan,
> I'm getting there, back from my course now! I'm still looking at the
> syslog.dox. I've found a document by Axel that I'm trying to
incorporate, so
> it's taking me a bit longer than anticipated.
>
> See here:
>
> http://haiku-os.org/documents/dev/system_logging
This document is quite detailed. At first I'd say: let's convert that
document to doxygen and let's just use it (with Axel's permission).
It's obviously a complete explanation of the system logger, not just a
tutorial. At the other hand, I don't know how much applications will
actually use this API. Maybe this document will be too much.
What do you think?
It may be too much, but if Axel has taken the trouble to write it, he must
have forseen a use for it by someone. Therefore I feel it should be included
somewhere at some time.
As how to convert this document: either we add the document as a
separate page, or we add the contents to the main content of the
syslog.dox file. The last solution is limited in the sense that you
cannot create subsections and headers. So I tend to incline to the
first one. However, I'd like to get some other thoughts on that (and
maybe we should ask Axel for permission first, and an opinion on the
cuality of this document).
I was looking at adding into the syslog.dox file. We could add in into a
seperate page, but there may be duplication between the content of that and
the existing page; is that acceptable? I could always strip out the
duplication though. I have experimented and you can use headings/subheadings
without the page tag within the syslog.dox file, but it might not be
formatted in the way we want. I can post an example if you like to check...
You are right however, we do need to check with Axel first, without his
permission this conversation becomes invalid.
Hopefully it's the correct thing to do for these documents. I personally
> think we should be quite verbose where possible.
Verbosity is good to a certain extend. We should try to remain a
reference document, not a tutorial. We should also prevent
concentrating too much on little, limited things (such as API's for
very specific buses). I'm not truely convinced that this document is
not too specific.
Niels
Yes, we should not concentrate on minor details. Maybe I'm being too
detailed. I just found Axel's document and thought it was good to give devs
and understanding of the mechanisms for system logging. At the end of the
day the documentation is there to help devs.
In order to not get bogged down, I can continue with my corrections, working
to the existing format of the syslog.dox file and submit my patch. Then, if
we/Axel agree, create a seperate page with his info on it minimising the
duplication accross the two docs. That way I can move on to the next task
without too much trouble.
What do you think?
Alan
Other related posts:
