[tor-bugs] #24497 [Webpages/Website]: Improve documentation for tor relay operators

Tue Jan 2 19:34:24 UTC 2018

#24497: Improve documentation for tor relay operators
------------------------------+------------------------
 Reporter:  arthuredelstein   |          Owner:  (none)
     Type:  defect            |         Status:  new
 Priority:  Medium            |      Milestone:
Component:  Webpages/Website  |        Version:
 Severity:  Normal            |     Resolution:
 Keywords:  ux-team           |  Actual Points:
Parent ID:                    |         Points:
 Reviewer:                    |        Sponsor:
------------------------------+------------------------

Comment (by alison):

 Here is the reply I sent to nusenu on the brief thread we had when trac
 was down:

 On 12/22/2017 04:47 PM, nusenu wrote:
 > Hello Alison,
 >
 > (I added Arthur since he opened the trac entry in the first place)
 >
 > I'll paste this email to #24497 once trac works again.
 Really it's perfect that trac went down so that we're all forced to take a
 real holiday. :)

 > thanks for your email and pushing this forward.

 Thank you for all the work you did on it.

 >
 >
 > Unfortunately trac appears to have some troubles currently
 > ("Service Unavailable" every now and then).
 >
 > Since no one objected so far (since 2017-12-19) I'll proceed with what I
 proposed on #24497.
 > (please speak up of you disagree with anything proposed on #24497)
 >
 > In addition:
 >
 > - lets not depend on: (which is currently the case)
 > https://www.torproject.org/docs/debian.html.en
 > I assume the new content will replace - not extend - it.
 Right, we should make the content at that address live on the wiki
 somewhere. I made a note of it to fix when trac comes back online.

 In Arthur's reply he suggested that we mirror the wiki on the website in
 order to keep it updated more easily and I think that sounds good.

 > - What is actually used to build/run community.tpo? (some known
 platform/cms?)
 > (I'm asking to find out if it would support that sources.list
 "generator")

 So there' s a ticket for website redesign that can get you up to speed
 when trac comes back:
 https://trac.torproject.org/projects/tor/ticket/21222

 The main piece of the website redesign (which, in addition to being a
 redesign of what we already have, will include this brand new thing) that
 is being worked on right now is support.torproject.org. That is being
 built in Lektor, which is a static website generator that also works as a
 CMS. I am not sure if that's what will be used on community.tpo, but if we
 want to know we can add hiro to this thread.
 > And does your timeline (blog post in first week of 2018) mean
 community.tpo is online by then?

 No, community.tpo won't be online then, it's gonna take some time. Without
 looking at the UX team roadmap (gee we sure do rely on trac for a lot) I
 believe that dev.tpo is gonna go after support.tpo. In any case, we are
 some time away from the community portal getting built. Meanwhile, we get
 a lot of questions through frontdesk at torproject.org asking for our relay
 resources to be better/easier/more complete, so I figure why not get the
 information out there to people now. Also, Phoul and I originally were
 thinking about a blog post to encourage relay operators before it merged
 with Arthur's ticket and irl's wiki page (synergy), so we're still
 thinking along that timeline.

 That said, if we want to mirror the wiki on the website, I'll change the
 blog post to just be something about how we recognized that these docs
 were wanting, and we made them better. And then I can say, stay tuned for
 this even better thing, community.tpo, which will have resources for relay
 operators and trainers and advocates and all the other neighbors and
 friends in Oniontown. And we can make sure to ask for feedback on the
 relay operator guide.
 > Just a short info on what I'll take care of - from the todo list (and
 complete before 2018-01-04
 > likely earlier):
 >>     add OS comparison table
 >>     add DNS on exit relays
 >>     add setting up outage notifications
 >>     add
 https://trac.torproject.org/projects/tor/wiki/OperatorsTips/DebianUbuntuUpdates

 Thank you!!!

 >
 >>     add Puppet to configuration management [we already have an Ansible
 role; is it necessary to have both?]
 > irl wanted to have more than one configuration management and I agree
 with him but only if it is maintained,
 > for at least 2 more years.
 >
 > Ideally some tpo person would review these external contributions, but I
 doubt that will happen
 > before you plan to publish.
 Good point...we should do that, or at least note that they haven't been
 reviewed.
 >
 >>     clarify meaning of Tor vs tor (near the top), and check this doc
 for consistency
 > I used "tor" where I was referring to the program and Tor everywhere
 else.

 Thanks for being consistent. This item is just noting that someone should
 go through and make sure that *everyone* who contributed did that. And
 then also define it for people using the document
 >>     remove "work in progress" header
 >>     make page read-only; accept changes via ticket
 > Who will take care of implementing changes after you turned into a read-
 only page?
 > (I'll certainly be someone that proposes updates)

 We did this with the support wiki to avoid malicious or unhelpful drive-
 bys. Anyone with an admin account on trac can edit read-only pages, but
 you (and Arthur) are right that it's not the best for participation and if
 we choose to mirror the wiki on the website instead it'll be easier for
 contributors.
 >
 >
 > Don't feel you have to reply to this email, lets keep the discussion on
 #24497.

 I would love to but trac is still down. I will update the ticket when trac
 comes back! Glad we had this email convo too.

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