[Outreachy] documentation: remove empty doc files #412
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Seems the CI build fails: |
Please also note that the PR description will be sent as cover letter. Maybe you want to change it a little? 😄 |
Right! Thanks 😄 |
HebaWaly
force-pushed
the
delete_empty_docs
branch
2 times, most recently
from
bc78a0d
to
ffdde61
Compare
|
/submit |
|
Submitted as pull.412.git.1571768375.gitgitgadget@gmail.com |
![gitgitgadget[bot]](https://avatars.githubusercontent.com/in/12836?s=60&v=4){kind=small}
| @@ -1,8 +0,0 @@ | |||
| grep API | |||
There was a problem hiding this comment.
On the Git mailing list, Emily Shaffer wrote (reply to this):
On Tue, Oct 22, 2019 at 06:19:35PM +0000, Heba Waly via GitGitGadget wrote:
> From: Heba Waly <heba.waly@gmail.com>
>
> 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 <heba.waly@gmail.com>
> ---
> 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
There was a problem hiding this comment.
On the Git mailing list, Junio C Hamano wrote (reply to this):
Emily Shaffer <emilyshaffer@google.com> writes:
> 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.
I'd approve this move, too, especially if we accompanied deletion
with addition (or verification of existence) of necessary docs
elsewhere (perhaps in *.h headers).
There was a problem hiding this comment.
On the Git mailing list, Heba Waly wrote (reply to this):
On Wed, Oct 23, 2019 at 10:05 AM Emily Shaffer <emilyshaffer@google.com> wrote:
>
> On Tue, Oct 22, 2019 at 06:19:35PM +0000, Heba Waly via GitGitGadget wrote:
> > From: Heba Waly <heba.waly@gmail.com>
> >
> > 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.
you're right!
> >
> > Signed-off-by: Heba Waly <heba.waly@gmail.com>
> > ---
> > 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
There was a problem hiding this comment.
On the Git mailing list, Heba Waly wrote (reply to this):
On Wed, Oct 23, 2019 at 12:52 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Emily Shaffer <emilyshaffer@google.com> writes:
>
> > 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.
>
> I'd approve this move, too, especially if we accompanied deletion
> with addition (or verification of existence) of necessary docs
> elsewhere (perhaps in *.h headers).
Good point, although not all corresponding header files are
documented, but I'll include that in the commit message.
Thanks
ffdde61
to
5cd79e2
Compare
|
/submit |
|
Submitted as pull.412.v2.git.1571815556.gitgitgadget@gmail.com |
| @@ -1,8 +0,0 @@ | |||
| grep API | |||
There was a problem hiding this comment.
On the Git mailing list, Emily Shaffer wrote (reply to this):
On Wed, Oct 23, 2019 at 07:25:56AM +0000, Heba Waly via GitGitGadget wrote:
> From: Heba Waly <heba.waly@gmail.com>
>
> Remove empty and redundant documentation files from the
> Documentation/technical/ directory.
>
> The empty doc files included only TODO messages with no documentation for
> years. Instead an approach is being taken to keep all doc beside the code
> in the relevant header files.
> Having empty doc files is confusing and disappointing to anybody looking
> for information, besides having the documentation in header files makes it
> easier for developers to find the information they are looking for.
>
> here's a list of the files removed and if the info can be found in the
> corresponding header file:
I think you can remove the above; in lots of composition contexts it
tends to be bad form to say "Here is <something>: <something>" - don't
warn us that you're going to present it, just present it. :) (Or, at
least, this has been drilled into my head by many high school English
teachers...)
Maybe you could say something like, "Some of the content which could
have gone here already exists elsewhere:" If you take that suggestion,
you can probably move grep.h to the bottom, as it's the exception which
doesn't have content that exists elsewhere.
> 1- Documentation/technical/api-grep.txt -> grep.h does not have enough
> documentation at the moment.
> 2- Documentation/technical/api-object-access.txt -> sha1-file.c and
> object.h have some details
> 3- Documentation/technical/api-quote.txt -> quote.h has some details.
> 4- Documentation/technical/api-xdiff-interface.txt -> xdiff-interface.h has
> some details.
For this list, I think you can remove the numbered bullet, and the
leading "Documentation/technical/" - we can see the files deleted from
the diff.
- Emily
There was a problem hiding this comment.
On the Git mailing list, Heba Waly wrote (reply to this):
On Thu, Oct 24, 2019 at 10:44 AM Emily Shaffer <emilyshaffer@google.com> wrote:
>
> On Wed, Oct 23, 2019 at 07:25:56AM +0000, Heba Waly via GitGitGadget wrote:
> > From: Heba Waly <heba.waly@gmail.com>
> >
> > Remove empty and redundant documentation files from the
> > Documentation/technical/ directory.
> >
> > The empty doc files included only TODO messages with no documentation for
> > years. Instead an approach is being taken to keep all doc beside the code
> > in the relevant header files.
> > Having empty doc files is confusing and disappointing to anybody looking
> > for information, besides having the documentation in header files makes it
> > easier for developers to find the information they are looking for.
> >
> > here's a list of the files removed and if the info can be found in the
> > corresponding header file:
> I think you can remove the above; in lots of composition contexts it
> tends to be bad form to say "Here is <something>: <something>" - don't
> warn us that you're going to present it, just present it. :) (Or, at
> least, this has been drilled into my head by many high school English
> teachers...)
>
> Maybe you could say something like, "Some of the content which could
> have gone here already exists elsewhere:" If you take that suggestion,
> you can probably move grep.h to the bottom, as it's the exception which
> doesn't have content that exists elsewhere.
That sounds better. Okay.
> > 1- Documentation/technical/api-grep.txt -> grep.h does not have enough
> > documentation at the moment.
> > 2- Documentation/technical/api-object-access.txt -> sha1-file.c and
> > object.h have some details
> > 3- Documentation/technical/api-quote.txt -> quote.h has some details.
> > 4- Documentation/technical/api-xdiff-interface.txt -> xdiff-interface.h has
> > some details.
>
> For this list, I think you can remove the numbered bullet, and the
> leading "Documentation/technical/" - we can see the files deleted from
> the diff.
yes.
> - Emily
Thanks
Remove empty and redundant documentation files from the Documentation/technical/ directory. The empty doc files included only TODO messages with no documentation for years. Instead an approach is being taken to keep all doc beside the code in the relevant header files. Having empty doc files is confusing and disappointing to anybody looking for information, besides having the documentation in header files makes it easier for developers to find the information they are looking for. Some of the content which could have gone here already exists elsewhere: - api-object-access.txt -> sha1-file.c and object.h have some details. - api-quote.txt -> quote.h has some details. - api-xdiff-interface.txt -> xdiff-interface.h has some details. - api-grep.txt -> grep.h does not have enough documentation at the moment. Signed-off-by: Heba Waly <heba.waly@gmail.com>
HebaWaly
force-pushed
the
delete_empty_docs
branch
from
5cd79e2
to
ee64a07
Compare
|
/submit |
|
Submitted as pull.412.v3.git.1571916551.gitgitgadget@gmail.com |
| @@ -1,8 +0,0 @@ | |||
| grep API | |||
There was a problem hiding this comment.
On the Git mailing list, Emily Shaffer wrote (reply to this):
On Thu, Oct 24, 2019 at 11:29:11AM +0000, Heba Waly via GitGitGadget wrote:
> From: Heba Waly <heba.waly@gmail.com>
>
> Remove empty and redundant documentation files from the
> Documentation/technical/ directory.
>
> The empty doc files included only TODO messages with no documentation for
> years. Instead an approach is being taken to keep all doc beside the code
> in the relevant header files.
> Having empty doc files is confusing and disappointing to anybody looking
> for information, besides having the documentation in header files makes it
> easier for developers to find the information they are looking for.
>
> Some of the content which could have gone here already exists elsewhere:
> - api-object-access.txt -> sha1-file.c and object.h have some details.
> - api-quote.txt -> quote.h has some details.
> - api-xdiff-interface.txt -> xdiff-interface.h has some details.
> - api-grep.txt -> grep.h does not have enough documentation at the moment.
>
> Signed-off-by: Heba Waly <heba.waly@gmail.com>
Reviewed-by: Emily Shaffer <emilyshaffer@google.com>
Thanks, Heba.
- Emily
|
This branch is now known as |
|
This patch series was integrated into pu via git@0df00d8. |
|
This patch series was integrated into pu via git@ab26659. |
|
This patch series was integrated into pu via git@765ee0d. |
|
This patch series was integrated into pu via git@c0036da. |
|
This patch series was integrated into next via git@c99fe16. |
|
This patch series was integrated into pu via git@223e70f. |
|
This patch series was integrated into pu via git@9a8f9d5. |
|
This patch series was integrated into pu via git@5c842d3. |
|
This patch series was integrated into pu via git@95d657c. |
|
This patch series was integrated into pu via git@1ce9065. |
|
This patch series was integrated into pu via git@e8def7a. |
|
This patch series was integrated into pu via git@5731ca3. |
|
This patch series was integrated into master via git@5731ca3. |
|
Closed via 5731ca3. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Remove empty and redundant documentation files from the
Documentation/technical/ directory.
The empty doc files included only TODO messages with no documentation for
years. Instead an approach is being taken to keep all doc beside the code
in the relevant header files.
Having empty doc files is confusing and disappointing to anybody looking
for information, besides having the documentation in header files makes it
easier for developers to find the information they are looking for.
Some of the content which could have gone here already exists elsewhere:
Signed-off-by: Heba Waly heba.waly@gmail.com