On Wed, Mar 26, 2025 at 8:07 AM Junio C Hamano <gitster@xxxxxxxxx> wrote: > > JAYATHEERTH K <jayatheerthkulkarni2005@xxxxxxxxx> writes: > > >> ... better to explain _why_ each change is made in the text that > >> precedes the sample code. E.g. > >> > >> Add `#include "config.h"` because you want to use X and Y, > >> and `#include "repository.h"` because you want to use Z. > >> > >> ... > > In the latest patch version I've removed the comments, since we > > already added a line above saying the user has to include > > `repository.h` I don't think we need to go in depth into that, do let > > me know if that is not the case, looking forward to any more feedback. > > It's your patch, after all. > > But if the reason why you added the comment was "this is a tutorial" > as you said, I would imagine that it would help readers to say why > a particular header is needed, when the tutorial text tells them > that they need to add it. From a quick look at the patch, it seems > that the updated text says what the change did (i.e. add a header), > which is rather obvious in the sample code, without saying why the > addition is necessary? > Agreed, but there will be two things from this point, in the previous documentation itself the header files didn't have very detailed explanation. If I do a detailed description of the header files in this specific tutorial/patch, the documentation will look inconsistent. I could do three things, 1. If these series of patches do not have any other faults/feedback, after merging them I could start working on a second microproject (Adding the details of header files of the whole document consistently). 2. I could present a change in this current patch to improve the details of the header files and re send the patch. 3. We can just leave this as is. I'm inclined towards the first idea, as I think this will cover my GSOC timeline and also give me some time to work on my proposal and fulfill my requirements for GSOC at the same time, and also makes the documentation good for newbies. But I'm willing to work with either of these ideas, or any new method you want to proceed with. I think the prev email was rendered in HTML So I resent this. Thank you, Jay
