[tor-dev] Improving PT documentation on website

George Kadianakis desnacked at riseup.net
Mon Jun 6 12:44:01 UTC 2016

Hello Nima,

I see you said this on IRC yesterday while referring to the pluggable transport
docs: "I'm gonna be working on some of these documentations this month. do you
have any suggestions on how we can improve them?"

I agree that this is extremely high priority right now and I'm very glad to see
you working on it. I feel that this is far more important than designing new
protocols at this point. The way I see it, our main issues with PTs at this
point is documentation and UX.

I imagine you are talking about https://www.torproject.org/docs/pluggable-transports.html.en
and maybe also the wiki page: https://trac.torproject.org/projects/tor/wiki/doc/PluggableTransports 

Some thoughts:

- With regards to the pluggable-transports.html.en page:
-- we should cleanup the PT list in the website. only include deployed PTs. 
   maybe even remove list entirely and move it to wiki. if that page is only for users, they don't need to know info about each PT.
-- add some sort of intuitive diagram similar to: https://www.torproject.org/images/obfsproxy_diagram.png
-- link to the new video as well
-- IMO we need a PT logo to give PTs a visual identity. When I wrote those pages, I used the moustached-onion logo. Do we have a better one?

- We also need up-to-date instructions on how to setup obfsbridges.
-- Maybe we need https://www.torproject.org/projects/obfsproxy.html.en but for obfs4
-- Here are the instructions that need to be updated: https://www.torproject.org/projects/obfsproxy-debian-instructions.html.en#instructions https://www.torproject.org/projects/obfsproxy-instructions.html.en#instructions
-- (but obfs5 is coming soon as well... PT deployment startegy not very good.)

- The wiki page is also quite bloated by now, and it's unclear what the audience is. 
-- The wiki page should also have links to user/bridge instructions, since
   that's where most people end up looking.
-- It might be worth cleaning it up, or splitting it in multiple pages.
   especially so since we link it from the main PT page.

I'm not very good with UX and web design stuff, but the above list would be the
things I would start addressing first...

Let me know what you think!

More information about the tor-dev mailing list