Subject: Re: [PATCH 1/1] documentation: remove empty doc files

From: Emily Shaffer <[email-masked]>
Date: Tue, 22 Oct 2019 14:04:58 -0700

On Tue, Oct 22, 2019 at 06:19:35PM +0000, Heba Waly via GitGitGadget wrote:
> From: Heba Waly <[email-masked]>
> 
> Remove empty and redundant documentation files from the
> Documentation/technical/ directory.
> 
> As part of moving the documentation from Documentation/technical/api-* to
> header files, the following files are deleted because they include only
> TODO messages with no documentation to be moved:
> Documentation/technical/api-grep.txt
> Documentation/technical/api-object-access.txt
> Documentation/technical/api-quote.txt
> Documentation/technical/api-xdiff-interface.txt

Same thing as I mentioned in your other review; what you've added to
your commit message now doesn't say anything you didn't say with the
diff. I can see that you removed empty documentation files; I can see
that those files include only TODO.

Maybe you can explain why it's a bad developer experience to stumble
across these, and that those files sat untouched for years in the
TODO(contributor-name) state.

> 
> Signed-off-by: Heba Waly <[email-masked]>
> ---
>  Documentation/technical/api-grep.txt            |  8 --------
>  Documentation/technical/api-object-access.txt   | 15 ---------------
>  Documentation/technical/api-quote.txt           | 10 ----------
>  Documentation/technical/api-xdiff-interface.txt |  7 -------
>  4 files changed, 40 deletions(-)
>  delete mode 100644 Documentation/technical/api-grep.txt
>  delete mode 100644 Documentation/technical/api-object-access.txt
>  delete mode 100644 Documentation/technical/api-quote.txt
>  delete mode 100644 Documentation/technical/api-xdiff-interface.txt

As for the content of this change, I absolutely approve. I've stumbled
across some of these empty docs while looking for answers before and
found it really demoralizing - the community is so interested in
teaching me how to contribute that they've sat on a TODO for 12 years?
:( I even held up api-grep.txt as a (bad) example in a talk I gave this
year. I'm happy to see these files go.

 - Emily