[tor-bugs] #2661 [Company]: Find best way to fit coding convention notes into wiki

[Tor Bug Tracker & Wiki]

#2661: Find best way to fit coding convention notes into wiki
------------------------------------+---------------------------------------
 Reporter:  tomb                    |          Owner:  tomb
     Type:  enhancement             |         Status:  new 
 Priority:  normal                  |      Milestone:      
Component:  Company                 |        Version:      
 Keywords:  wiki coding convention  |         Parent:      
   Points:  1                       |   Actualpoints:      
------------------------------------+---------------------------------------

Comment(by rransom):

 Replying to [comment:4 tomb]:
 > Replying to [comment:3 rransom]:
 > > Replying to [ticket:2661 tomb]:
 > > Information on the wiki is less likely to be seen (and far less likely
 to be trusted) by the new volunteers who need to see it than information
 in Git.
 > >
 > > The best way to make the HACKING file more useful is to put it in the
 root directory of the Tor Git repo (rather than hiding it under doc/ where
 it is now), and keep it up to date.
 >
 > I do have one question about this, which is that some people may check
 out some piece of Tor other than tor.  For example, my target audience
 with the R coding conventions may be people who are just checking out
 metrics, or torperf.  What is the best way to help such people find the
 information?

 Put the information in a file named `HACKING` in the root directory of the
 repository to which it is relevant.  If you need to have more than one
 such file, create a directory named `HACKING.d` in the root directory of
 the repository, and put your informational files in there.

 > Word of mouth is great, but doesn't scale well.  I fortunately found and
 read HACKING early on, but only because I chose to do a long march through
 all the files in the main tor repository.  I am not sure I would want to
 expect, for example, an undergrad trying to make a small contribution as a
 class project to have to do this.

 I didn't see the HACKING file until you filed this ticket, because it was
 hidden away inside the doc/ directory next to the man pages and a pile of
 obsolete TODO files.  I learned most of Tor's coding conventions by
 reading the source code for a few minutes.

 > I note that when I google for "tor coding convention" the only relevant
 hit is this ticket.  I did a non-scientific totally random set of google
 searches on some of the phrases in the HACKING file and got no relevant
 hits on the first page of results.

 I don't quite understand why anyone would expect Google to turn up useful
 information about a project's coding conventions, but the solution to this
 problem is to make Google index the important parts of our Git
 repositories.

 > I am not at all suggesting that the wiki is the only or the best way to
 make this information accessible, but I am willing to spend time
 implementing whatever people decide is a better solution.

 The wiki is a strictly worse place for this information than a `HACKING`
 file in its conventional location inside the relevant source code
 repository.  Every developer who works on source code in a repository
 would have easy access to a copy of the HACKING file at the same time, but
 reading a 'coding conventions' wiki page would require a good Internet
 connection.

-- 
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/2661#comment:5>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online