[Xapian-devel] GSoC - Follow up Question about doc

[Dan Colish]

> 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