Developer and Documentation Portals

Organising the structure and content for the new developer and documentation Portals

Facilitator(s): pili

Duration: 1h

Audience: Representatives from development teams at Tor, anyone interested!


We need a dedicated place for developers to find out how to Hack on tor and all of the different projects available

Rough Agenda:

  • Current status
  • Review previous work and brainstorm changes/updates
    • Brainstorm sitemap
    • Brainstorm ideas for content, e.g
      • place to host introductory documents for new contributors
      • links to good first bugs,
      • own projects that we want to feature
      • secondary list of other projects that are developed by others and we want to feature



Related Tickets



Meeting Notes

  • would be the new portal
    • should have section for teams
    • onboarding material
    • projects teams work on
    • roadmaps
    • ...
  • old website has tons of information
    • hard to find where things are and where to get started
    • was more about organisation and entry point into tor
  • boundary between tech and docs?
    • is specs etc. + more like references + has both user and dev-focused docs
    • is teams and how to get started + where to go to get started
    • boundaries seem a bit blurry
  • some discussion on where the boundary is between dev/doc/user portal
  • dev portal should be useful to both existing *and* new devs
    • otherwise little incentive for old devs to maintain it
  • we reviewed wireframe of old mockup for dev portal
    1. tor ecosystem diagram
    2. areas of work
      • we're discussing what teams should be on there. not all are "easy to join", e.g. sysadmin team
    3. research section should just point to
  • we want dev portal for both internal and external folks
    • again, otherwise no incentive for maintenance
  • new devs may be more interested in broad areas and not in teams
  • should have the following teams listed
    • network
    • metrics
    • applications
    • ooni
    • anti-censorship
    • ux, fundraising, community not necessary here
  • for each team we have landing pages that would replace trac
    • mailing list
    • weekly irc meeting
    • ... (see pic)
  • how much integration between trac/portal/gitlab?
  • projects should have a clear descriptions of what they do
    • annoying if one has to figure that out by clicking five layers deep
  • we want different "views" on the old projects table
    • have tags that allow people to filter our projects
    • one tag could be responsible team
    • tags: maintained/unmaintained, programming language (can be multiple), team, target audience (end user, researcher, ...), volunteers needed, theme (cryptography, ...), maturity (alpha etc.), license
  • how do we handle maintenance to reduce friction?
    • if we cannot edit something easily, it will be out of date
    • each team should be free to edit its own documentation
    • we could "isolate" commits to team by writing receive hooks that reject commit if you edit something you're not allowed to
  • we want to make our stuff discoverable. a simple search bar makes this difficult because you don't know what to search for
    • we want some kind of site index (ugly but useful)
  • ecosystem diagram neat but hard to make accessible, esp. for impaired people
    • developers like hierarchies. expandable is fine.
  • rust docs are great (learn rust, improve in rust, master rust)
  • notes taken by phw@… -- please ask if anything doesn't make sense
  • [Pili] There was a comment after this session about the possibility of having an engineering blog separate from the main tor blog and with a feed into this portal to share some more technical topics
Last modified 16 months ago Last modified on Jul 16, 2019, 9:55:32 AM