Opened 7 years ago

Closed 5 years ago

#7376 closed task (fixed)

Reorganize the documentation

Reported by: hellais Owned by: hellais
Priority: Very High Milestone:
Component: Archived/Ooni Version:
Severity: Keywords: ooni_documentation, SponsorH201212, quickfix
Cc: Actual Points:
Parent ID: Points:
Reviewer: Sponsor:

Description

Currently our documentation is a mess.

It is distributed across multiple different places and there is no central way of knowing which one is right.

Here is the list of all the current documentation locations:

https://trac.torproject.org/projects/tor/wiki/doc/OONI/ThreatModel

https://trac.torproject.org/projects/tor/wiki/doc/OONI/TestWritingMethodology

https://trac.torproject.org/projects/tor/wiki/doc/OONI/Architecture

https://trac.torproject.org/projects/tor/wiki/doc/OONI/Backend

https://trac.torproject.org/projects/tor/wiki/doc/OONI/Tests

https://trac.torproject.org/projects/tor/wiki/doc/OONI/DataCollection

https://trac.torproject.org/projects/tor/wiki/doc/OONI/SetupHowto

http://ooni.readthedocs.org/en/latest/

We are currently using for the developer documentation readthedocs.org: http://ooni.readthedocs.org/en/latest/

The reason for doing so is that it will automatically build the sphinx documentation for us and we don't have to worry about setting up anything on torproject machines to create these docs.

The documentation that is currently stored on the wiki should be moved to .rst files that are in:

https://gitweb.torproject.org/ooni-probe.git/tree/HEAD:/docs/source

Child Tickets

TicketStatusOwnerSummaryComponent
#7759closedhellaisAdd section for DataCollection to ooni websiteArchived/Ooni
#7760closedhellaisAdd installation instructions for OONI to the documentationArchived/Ooni
#7761closedhellaisAdd ThreatModel page to ooni documentationArchived/Ooni

Change History (8)

comment:1 Changed 7 years ago by hellais

Keywords: SponsorH201210 added

comment:2 Changed 7 years ago by hellais

Keywords: ooni_documentation added; documentation removed

comment:3 Changed 7 years ago by hellais

Keywords: SponsorH201208 added; SponsorH201210 removed

comment:4 Changed 7 years ago by hellais

Keywords: SponsorH201210 added; SponsorH201208 removed

Moving to third milestone

comment:5 Changed 7 years ago by aagbsn

Documentation is now located at https://ooni.torproject.org/docs.

https://trac.torproject.org/projects/tor/wiki/doc/OONI/ThreatModel
is not yet ported to ooni.torproject.org/docs

https://trac.torproject.org/projects/tor/wiki/doc/OONI/TestWritingMethodology
is now: https://ooni.torproject.org/docs/writing_tests.html

https://trac.torproject.org/projects/tor/wiki/doc/OONI/Architecture
is now: https://ooni.torproject.org/docs/architecture.html

https://trac.torproject.org/projects/tor/wiki/doc/OONI/Tests
see: https://ooni.torproject.org/docs/index.html#core-ooniprobe-tests
and: https://ooni.torproject.org/docs/nettests/modules.html

https://trac.torproject.org/projects/tor/wiki/doc/OONI/DataCollection
This needs to be more thoroughly documented and linked to the oonib documentation. For example, there should be a page describing the report format, and also link to the backend setup and use of ooni-probe with a collector. See also below:

https://trac.torproject.org/projects/tor/wiki/doc/OONI/Backend
is briefly mentioned here: https://ooni.torproject.org/docs/index.html#oonib
and: https://ooni.torproject.org/docs/architecture.html#oonib
It should have its own page with sections for setting up the backend (similar to or taken from oonib/README.md) and test helpers, and document what each test helper does.

https://trac.torproject.org/projects/tor/wiki/doc/OONI/SetupHowto
This page points at the readthedocs site which in turn points to:
https://github.com/hellais/ooni-probe#getting-started (which displays the README.md file). We should replace this link with a page generated from the README.md file and host it on ooni.torproject.org

comment:6 Changed 7 years ago by hellais

Keywords: quickfix added

comment:7 Changed 7 years ago by hellais

Keywords: SponsorH201212 added; SponsorH201210 removed

comment:8 Changed 5 years ago by hellais

Resolution: fixed
Status: newclosed

This is fixed.

Note: See TracTickets for help on using tickets.