get first iteraion of design and code for dev.torproject.org

This is the main ticket for the work related to creating dev.torproject.org

• Main stakeholders of this project:
• Designer for this project: Duncan
• Developer for this project: Kez
• PM for this project: Gaba

Project phases:

• 0. content architecture - map current content related to the portal and organize it
• 1. whiteboard draw organization of the content into pages
• 2. wireframe these pages
• 3. create design for these pages [these include design reviews till we are happy with what we have]
• 4. start organizing content for the pages (with the design already done we will be working with that)
• 5. update high definition mockups with real content
• 6. guerrilla user testing #1
• 7. start coding the pages * [ ] 8. once content is finished we upload them on transifex for translation to start
• 9. Once coding is done we can start QA by language (as translations gets complete)
• 10. [we could do another user test here too before launch if we want - or we can run one after lunch and continue iteration]

Update May 2023: we will do the deployment only in English and have translations in the future.

changed milestone to %website redesign in legacy/trac

added component::webpages/website in Legacy / Trac milestone::website redesign in Legacy / Trac owner::isabela in Legacy / Trac parent::21222 in Legacy / Trac priority::medium in Legacy / Trac severity::normal in Legacy / Trac status::assigned in Legacy / Trac type::defect in Legacy / Trac ux-team in Legacy / Trac labels

Trac:
Description: This is the main ticket for the work related to creating dev.torproject.org

• Main stakeholders of this project: 
• Designer for this project: Antonela
• Developer for this project: Hiro
• PM for this project: Isabela

to

This is the main ticket for the work related to creating dev.torproject.org

• Main stakeholders of this project:
• Designer for this project: Antonela
• Developer for this project: Hiro
• PM for this project: Isabela

Project phases:

0. content architecture - map current content related to the portal and organize it

1. whiteboard draw organization of the content into pages

2. wireframe these pages

3. create design for these pages [these include design reviews till we are happy with what we have]

4. start organizing content for the pages (with the design already done we will be working with that)

5. update high definition mockups with real content

6. guerrilla user testing #1

7. start coding the pages

8. once content is finished we upload them on transifex for translation to start

9. Once coding is done we can start QA by language (as translations gets complete)

10. [we could do another user test here too before launch if we want - or we can run one after lunch and continue iteration]

Trac:
Cc: antonela, hiro to antonela, hiro, boklm

Trac:
Username: tseretni-rmd
Cc: antonela, hiro, boklm to antonela, hiro, boklm, tseretni-rmd

mentioned in issue legacy/trac#28532 (moved)

mentioned in issue legacy/trac#28549 (moved)

mentioned in issue legacy/trac#29200 (moved)

moved from legacy/trac#24132 (moved)

Hi! The last piece of the big tpo.org overhaul is dev.torproject.org.

As in the project description, dev.torproject.org aims to be the landing page for technical users, mainly developers, who aim to:

• Exploring the Tor ecosystem of apps
• Contributing to the network and related projects
• Hacking on Tor

We discussed it during previous dev meetings

https://trac.torproject.org/projects/tor/wiki/org/meetings/2019Stockholm/Notes/DevPortal

We have a tentative spreadsheet of all the content we want to organize

https://nc.torproject.net/s/SJLHZYQdAkM24mX

And, I came up with a first attempt at the information architecture [1, 2], which will be open for review until the end of the month.

We want to have your feedback on this before jumping on building what we are wireframing in staging.

I'm using a .md format here to allow anyone to make edits and/or make suggestions about what we are missing or what we should remove because is obsolete. If you have a suggestion, please also link to where the current content is living, so we can move it smoothly.

dev.tpo-v0.md

Let me know what do you think! @tpo/core @tpo/metrics @tpo/anti-censorship @tpo/applications

Other Projects Developers portals (for inspo )

• https://nextcloud.com/developer/
• https://docs.gitlab.com/
• https://plaid.com/docs/
• https://docs.blockstack.org/
• https://developers.cloudflare.com/
• https://developer.mozilla.org/
• https://developer.ibm.com
• https://developers.libra.org/
• dat://beakerbrowser.com/docs/
• https://matrix.org/docs/develop/
• https://docs.microsoft.com/en-us/
• https://www.debian.org/devel/
• https://documentation.divio.com/

cc @pili

added UX label

added Bug label and removed 1 deleted label

assigned to @antonela and unassigned @isabela

added Sponsor 9 + 1 deleted label and removed Bug label

changed the description

added Bug label and removed 1 deleted label

Some thoughts and questions:

• I like how the landing page prominently features our areas of work.
• Can or should these areas of work replace the team pages we had on our trac wiki? I find lektor pages easy to curate and I would be happy moving (most of) our team wiki page to dev.tp.o. If that's the plan, we should probably add IRC meeting schedules, important mailing lists, and roadmaps to each area of work. Each area of work should have a point of contact, so volunteers know how to get in touch if they have questions.
• I don't understand how the dev.tpo-v0.md document relates to the content at https://lektor-staging.torproject.org/dev/staging/. Does the .md document contain a table of contents that will eventually live at dev.tp.o?

I'm probably stating the obvious here but we should organise the dev portal so it's easy for volunteers with common questions to find the resource they need. Common questions that come to mind:

• "I'm interested in topic X. How can I contribute?" (Our areas of work should answer this.)
• "I know programming language Y. How can I contribute?"
• "I'm looking for a research problem to work on. What's next?" (The link to the research portal will help.)
• "I'd like to contribute but I don't know how to get started; nor what my options are."

Thanks for your review, Philipp!

Replying inline:

Can or should these areas of work replace the team pages we had on our trac wiki? I find lektor pages easy to curate and I would be happy moving (most of) our team wiki page to dev.tp.o. If that's the plan, we should probably add IRC meeting schedules, important mailing lists, and roadmaps to each area of work. Each area of work should have a point of contact, so volunteers know how to get in touch if they have questions.

That is a good idea. I wonder what other teams think. Now people are working on updating wikis so let's see how the content across teams settles.

I don't understand how the dev.tpo-v0.md document relates to the content at https://lektor-staging.torproject.org/dev/staging/. Does the .md document contain a table of contents that will eventually live at dev.tp.o?

Yes. Staging now is just a skeleton. @pili has been moving content but I aim to first define the content and then finish the migration. Just to have an idea, here are the mockups of the templates/structure we are planning to use (all this have dummy content):

Homepage: https://marvelapp.com/4471ig9/screen/38979926

Team: https://marvelapp.com/4471ig9/screen/38979951

Project: https://marvelapp.com/4471ig9/screen/38979975

I'm probably stating the obvious here but we should organise the dev portal so it's easy for volunteers with common questions to find the resource they need. Common questions that come to mind: "I'm interested in topic X. How can I contribute?" (Our areas of work should answer this.) "I know programming language Y. How can I contribute?" "I'm looking for a research problem to work on. What's next?" (The link to the research portal will help.) "I'd like to contribute but I don't know how to get started; nor what my options are."

Yes, having the ability of listing projects that are filterable by language is useful. If you see the mockups, we planned to have some kind of tags in the fashion of pills to do it. Maybe, we will need a table view with all the projects to enable filtering. That is a good idea. With lektor databags that should not be so hard.

Organizing the main page by areas of work can be a per-topic approach. Yes, "how i can contribute" should be everywhere. We can use it as a callout as we have in commununity.tpo eg https://community.torproject.org/localization/ "Can you help us improve our translations?"

• Can or should these areas of work replace the team pages we had on our trac wiki?

I like this idea.

added Doing label

added 1 deleted label and removed Doing + 1 deleted label

removed Bug label

Hello!

I'm attaching a suggested information architecture as I understand it. It is less organized by team, and more organized by type of project. For people who aren't sure what "type of project" they want, it starts out with two more general topics. I've included example headings for most of the categories, to explain what I mean.

This architcture also includes an outline of the information I think we should present for each project -- both projects where we are the primary web presence, and projects where we aren't.

Finally there are a few suggestions at the bottom.

nm-edits.txt

I really like this structure that Nick is proposing.

Here come a couple of comments from my side both for the general layout/part and for the more applications-related side

1. General

   1. I like the idea of starting the landing site with some context as @nickm's comments indicate. Giving an overview and general areas where we outline how and where folks can help sounds good to me.
   2. I looked over the mock-ups a bit and compared to what we have on staging right now. Let's not make the developer portal into some team exhibition but group it loosely around code areas. We don't have teams right now and someone interested in dev work is likely not interested in teams anyway (at least not at the beginning).
   3. I like @nickm's idea as well to make it clear what are external projects and what are parts that we consider internal. Linking to the former is fine/enough (with the outline Nick suggested) and we should expand the latter on our dev portal (again Nick's suggestions seem to be good ones here to me, too).

2. Applications

   1. I think we should not have different points for Tor Browser and Tor Browser on Android. We don't have a point for Tor Browser on Windows either. Just Tor Browser and then we can link to all the repos and explain the structure of it etc.
   2. I would not mention HTTPS-Everywhere nor Tor Messenger. The latter is dead and the former is not maintained by us anymore. We could link to it as an external project when we talk about Tor Browser, though.

I would not mention HTTPS-Everywhere nor Tor Messenger. The latter is dead and the former is not maintained by us anymore. We could link to it as an external project when we talk about Tor Browser, though.

That's reasonable. I'm not sure at all sure that I got the list of projects right, or that it's complete: I bet we'll find other projects that we want to move, remove, or add as we move forward.

added Doing label

Thanks for your review @nickm! I iterated your attachment and proposed some titles for each section. Overall, the sections are maintained but the hierarchy changed. I think this is sensible and works better than the original per team approach.

Some comments:

• I'll need some help in finding the content in 2019.tpo for filling some sections. Creating new content is out-of-scope for this release given our capacity. I marked the sections I'm not sure where to look at with a [?].
• "Observing the tor network" seems the section for metrics and other measurement projects; I wonder if we should give more predominance to metrics in that area. Also, 'Observing'? what do you think? cc @karsten
• Onion services don't exist in this portal besides Onionbalance. Is it good? Are we missing anything?

The next step is filling the spreadsheet with the URLs we are using from 2019 and the new ones. With this work, we minimize the "broken URLs" issue when we redirect from 2019.tpo.

Also during July, we will start filling up dev.tpo with this new accorded structure.

dev.tpo.v0.1.md

Thanks, @antonela!

I can try to find content and fill things in; in some cases, we'll probably want to use stuff from the wiki. In other cases, I'm not the best person to find it.

I do not think that the list of projects I made is at all complete: we'll need to update it as we work through the old site, I believe. Is that good enough for now: getting the architecture figured out now, and filling in more projects as we move ahead?

These items that you marked with ? are ones that I do know how to find:

• Other tor implementations https://trac.torproject.org/projects/tor/wiki/doc/ListOfTorImplementations
• "guide to writing tor applications", "guide to using tor-api.h" -- my team should write these, or they shouldn't go in. :)

I think the other items on the list that you marked with ?, are ones that I took from your list. I'm okay with removing them if we don't have text there. :)

@juga worked on dev documentation in gitlab pages itself. Maybe we can do something similar here. Their work:

• In gitlab pages https://koverto.gitlab.io/koverto/
• In read the docs https://sbws.readthedocs.io/en/latest/

• In gitlab pages https://koverto.gitlab.io/koverto/

and it is automatically deployed by the Gitlab CI (https://gitlab.com/koverto/koverto/-/blob/mainline/.gitlab-ci.yml#L179)

• In read the docs https://sbws.readthedocs.io/en/latest/

if we (will) have Gitlab pages enabled, i'd move this documentation to the pages and also deploy automatically with Gitlab CI.

In case it is useful here, other thing that i commented in trac#29200 (comment 2557655), i generated some of the tor documentation with sphinx and upload it to readthedocs. It could also be Gitlab pages. You can see it at:

• https://torguts.readthedocs.io/en/latest/
• https://tor-core.readthedocs.io/en/latest/

moved from trac#24132 (moved)

changed milestone to %Sponsor 9 - Phase 4 - Usability and Community Intervention on Support for Democracy and Human Rights

unassigned @antonela

added Backlog label and removed Doing label

removed milestone %Sponsor 9 - Phase 4 - Usability and Community Intervention on Support for Democracy and Human Rights

mentioned in commit antonela/dev@6e64a766

mentioned in merge request !1 (merged)

So! I finally updated staging with the new proposed structure. We now can start to fill in it with content.

• I mapped urls here: https://nc.torproject.net/apps/onlyoffice/12070?filePath=%2FWebsites%2FDeveloper%20Portal%2FCopy%20and%20Sitemap.xlsx

• I worked with content here

1. 6e64a766
2. a074e417

• I made a clean up before starting here

1. 24c79b56

v0.2_-_Copy_and_Sitemap.pdf

I like the structure and the name of the sections like "Observing the network". This last one is missing some stuff like onionperf but I guess that is easy to add.

@hiro cherry-picked my commits and now staging is ready for getting content

https://lektor-staging.torproject.org/dev/staging/

cc @gus @pili

added Icebox label and removed Backlog label

assigned to @duncan

removed Icebox label

added Backlog label

added Next label and removed Backlog label

added Doing label and removed Next label

Let's add a square called "Hacking on localization" to the page "http://y7pm6of53hzeb7u2.onion/dev/staging/hacking-on-tor/index.html" so we can put localization in the same level as all the other hacking/documenting/researching at Tor. The content is the one that @emmapeel is working on in:

https://gitlab.torproject.org/tpo/community/l10n/-/wikis/Localization-for-developers

Thanks @gaba, I've added it into the spreadsheet but may shuffle around its final title/location.

Is this a folder you can give me full access to on NextCloud by any chance?

https://nc.torproject.net/s/SJLHZYQdAkM24mX

I have some documents I'd like to upload there for safekeeping.

I can not share that folder in nc (it was created by pili) but I can create a new developer portal folder that we can control and keep those files plus the ones you have.

That would be great, thanks Gaba!

Here's a brief summary of the activity on this ticket over the past couple of weeks (for future reference):

• We shared a project update at the All Hands on 09-03-2021, the presentation for which can be viewed again on NextCloud.
• During the All Hands we allocated time for a content workshop (slides 9–10), within which the wider team were invited to discuss and feedback on our proposed structure, and assign "content owners" who'll be responsible for delivery of their respective pages/sections. A carbon copy of the spreadsheet as it was at the end of the workshop can be viewed on NextCloud too – however please ping Gaba or myself for a link to the working file.
• The working spreadsheet was recirculated among attendees via email to continue to edit for a period of two further weeks, which has now come to a close.

And here are the next tasks for this project in our todo list:

1. Review and tidy up the spreadsheet outputted from the workshop.
2. Make any necessary commits to the staging site to reflect the above.
3. Outline what the content delivery pipeline looks like (e.g. @antonela suggests we have content owners add their content directly to the repo via lektor, in the agreed upon locations, to be copyedited in-place by the wider project team – which I think sounds good!).
4. Reach out to the assigned content owners and agree on reasonable timeframes for content population.

Thanks!

added Next label and removed Doing label

changed milestone to %Developer portal

added Backlog label and removed Next label