Opened 2 months ago

Closed 5 weeks ago

#31943 closed enhancement (implemented)

Review pull request: reorganized Tor manual

Reported by: swati Owned by: swati
Priority: Medium Milestone: Tor: 0.4.3.x-final
Component: Core Tor/Tor Version:
Severity: Normal Keywords: gsod, documentation
Cc: Actual Points:
Parent ID: Points:
Reviewer: catalyst Sponsor:

Description


Child Tickets

Change History (14)

comment:1 Changed 2 months ago by swati

Created the Pull request - https://github.com/torproject/tor/pull/1391.

Please review the Tor Manual for the following updates:

  • Created a table of contents for this page. Users can navigate to different sections of the Tor Manual easily.
  • Regrouped the following topics under the umbrella Reference section - Signals, Files, See Also, Bugs, Authors.
  • Arranged the information in the Files section in tabular format. Please review whether this format works.
  • Rearranged and formatted information in the Command-Line Options.
  • Ongoing process - editing, proofreading and formatting the existing content to ensure correct grammar usage, standard terminology usage, and correct formatting of command/option names etc.
Last edited 2 months ago by swati (previous) (diff)

comment:2 Changed 2 months ago by swati

Last edited 2 months ago by swati (previous) (diff)

comment:3 Changed 2 months ago by nickm

Milestone: Tor: 0.4.3.x-final
Status: newneeds_review
Summary: Review pull requestReview pull request: reorganized Tor manual

comment:4 Changed 2 months ago by gaba

Keywords: gsod documentation added

comment:5 Changed 2 months ago by teor

Type: defectenhancement

We're still making a few changes to the Tor manual in 0.4,2, how are we going to avoid conflicts with this re-organisation?

comment:6 Changed 2 months ago by teor

Owner: set to swati
Status: needs_reviewassigned

comment:7 Changed 2 months ago by teor

Status: assignedneeds_review

comment:8 in reply to:  5 Changed 2 months ago by nickm

Replying to teor:

We're still making a few changes to the Tor manual in 0.4,2, how are we going to avoid conflicts with this re-organisation?

If there are conflicts with this merge in particular, I think we should resolve them by hand, unless Swati knows how and would rather do it.

In general, I think that maybe we should limit the number of manual changes we make while Swati is working on the reorganization, and we should encourage Swati to make frequent PRs so that the possible conflicts don't build up over time.

comment:9 Changed 2 months ago by dgoulet

Reviewer: nickm

comment:10 Changed 2 months ago by catalyst

Reviewer: nickmcatalyst

comment:11 Changed 8 weeks ago by catalyst

Thanks for contributing these changes! I've taken most of the changes to the FILES, SEE ALSO, and BUGS sections and put them in a separate ticket, #32176. We can work on incorporating your other changes once we have that merged.

Generally, we tend to use imperative tense when describing things like command line options. (We also use imperative tense when documenting what C functions do.) For example, we prefer "Specify a file..." to "Specifies a file...". If we're not consistently using imperative tense for command line options, it might be better to fix the exceptions rather than change everything else to not use the imperative. What do you think?

I did notice that somehow the changes in e5cf1423fdc1707093885e5d74f0691de3365b55 got reverted in your patch. I think it would be good for us to understand how that happened. Please feel free to reach out to me or ahf for help with that if you need.

comment:12 Changed 7 weeks ago by catalyst

Created a separate ticket, #32277, containing the changes to the DESCRIPTION and COMMAND-LINE OPTIONS sections.

The only remaining changes seem to be some minor restructuring of section headings. Swati, please let me know if I've missed anything.

comment:13 Changed 7 weeks ago by catalyst

Status: needs_reviewneeds_information

Need to check with swati if there are additional changes that we haven't yet incorporated that need looking at.

comment:14 Changed 5 weeks ago by catalyst

Resolution: implemented
Status: needs_informationclosed

Implemented by #32277, #32176. Thanks, swati!

Note: See TracTickets for help on using tickets.