Xapian devel - May 2012 - GSoC - Follow up Question about doc

Dan Colish,

I am facing major issues in the documentation. Have invested quite some
time but not able to properly figure out what really needs to be done in
the documentation.

Can you please once again, clearly mention the objective of  a "user
documentation".
Also, can you please guide as to how to give an overall view? I am not able
to figure out what really needs to be added.

Also, it seems that I have wasted much of my time and energy in explaining
the things which were not meant to be explained. Have tried to removed them
from the doc.
This could have been avoided if I had come up with smaller chunks rather
than coming up with a single large chunk.

Have also added some replies regarding the comments you made on my github
commit. Reply to them when you can.
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.xapian.org/pipermail/xapian-devel/attachments/20120523/62155281/attachment-0001.html>

> Can you please once again, clearly mention the objective of a "user
documentation".
> Also, can you please guide as to how to give an overall view? I am not able
to figure out what really needs to be added.
> 
Ok, so I was really suggesting that most of the documentation that lives outside
of our doxygen generated API documentation is consider to be higher level user
docs. The actual user can vary widely from a new xapian user to core developers,
but the intention of that documentation should be to describe in high level
language the objects being documented. Describing all the methods might not be
useful in that scenario. What's important is to capture the critical code
path's and interfaces, and preferably show a few examples as
well.
> 
> Also, it seems that I have wasted much of my time and energy in explaining
the things which were not meant to be explained. Have tried to removed them from
the doc.
> This could have been avoided if I had come up with smaller chunks rather
than coming up with a single large chunk.
> 
I don't think what you have do has been a waste at all; it just needs a
little tweaking. All of the documentation that you've created to this point
can be used, the question is where it really belongs.  As I said above, I think
you need to split it into a few parts and focus on the audiences involved. For
basic docs, you're usually writing for xapian end-users. For docs that cover
internals at a high-level, you're writing for xapian developers. For docs
that describe precise implementations in their entirety, you are mostly writing
API comments for doxygen.

Your observation about breaking down the commits into smaller chunks is very
good. If the changes are a little smaller we'll be able to review and
correct more quickly and hopefully avoid any frustrations.
 
--Dan