General improvements to documentation

[ErikBjare]

The docs are okay, but they have gotten a bit unstructured over time as we've just kept piling things on without any "refactoring". Here are some of the issues I'd like to resolve.

We welcome feedback and pull requests on any of these tasks! We need a fresh set of eyes!

General

• [ ] Clean up structure/old sections (careful not to break any links)
  • [x] The user/developer split doesn't make much sense (kinda fixed in https://github.com/ActivityWatch/docs/pull/53)
  • [x] Many of the top-level pages should be subpages ("Running on Gnome", "REST API") (fixed in https://github.com/ActivityWatch/docs/pull/53)
  • [x] The order of pages don't make sense ("Installing from source" is way too far down, for example) (fixed in https://github.com/ActivityWatch/docs/pull/53)
  • [x] "Development" is a terrible page header (fixed in https://github.com/ActivityWatch/docs/pull/53)
  • [ ] Avoid breaking old links (didn't find a nice way to do this...)
• [x] Document where ActivityWatch stores data, cache, logs. (see: https://github.com/ActivityWatch/activitywatch/issues/521)
• [x] The FAQ isn't really a FAQ, it's just a bunch of random questions that should probably be answered elsewhere in the docs (many of them already are)
  • It served its purpose before we had decent docs and just needed to write down a few quick answers.
  • The FAQ should have short answers, with links to additional details.
• [x] Better interlinking in general (partially done in https://github.com/ActivityWatch/docs/pull/53)
• [ ] Document where nightly builds can be obtained (see https://github.com/ActivityWatch/activitywatch/issues/507)
• [ ] Document (and warn!) about opening ActivityWatch to the network
  • Setting the listening address (and security implications)
  • Using an SSH tunnel instead
• [ ] Document how ActivityWatch is not designed to monitor employees.
  • We do not want people to be forced to use ActivityWatch in a way where their data is stored by/sent directly to their employer.
  • However, we might implement a "report" feature (https://github.com/ActivityWatch/activitywatch/issues/233), which (imo) is the privacy-aware way to approach the issue.

Features

• Categories
  • [ ] Maybe document how to export/import categories from/to local storage?
  • [ ] Explain how categories are applied in more detail (avoiding misunderstandings like in https://github.com/ActivityWatch/activitywatch/issues/517)
  • [ ] Link to categorization docs from category settings
  • [ ] Link to regex101 or similar (we should maybe do this straight from the web UI as well?)
• [x] ~~Add basic documentation of queries and transforms (with links to examples)~~ Edit: Nvm, this was mostly done.
• [ ] Update the 'filtering data' section with link to aw-client redaction example
• [ ] Document the 'edit view' functionality
• [ ] Add screenshots of category rules?

Security

• [x] Add mention of ActivityWatch being "unsafe" on multi-user systems (see https://github.com/ActivityWatch/activitywatch/issues/75)

Examples

• [x] Add Examples page, which contains all other "Examples"-like pages ("Creating your first watcher", "querying data", parts from "Extending ActivityWatch")
• [x] aw-client now contains a few examples that are suitable for use in documentation, link/reference them.
• [ ] Add example for a 'canonical events' query (like the base query of the same name in aw-webui)
• [ ] Add example for analyzing data outside of ActivityWatch (https://github.com/ActivityWatch/activitywatch/issues/363)
  • [x] Add example for reading into pandas (see: https://github.com/ActivityWatch/activitywatch/issues/339) (done in https://github.com/ActivityWatch/aw-client/commit/9de80950e8623450e77231ea66c5dc5df473b68a)
  • [ ] Visualize data using matplotlib
    • Would be cool to do with sphinx gallery (but might be overkill and require a lot more time than reasonable with setting up the server with fake data and all)

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[ArchaeotheriumSapienter]

Can I take a shot at this? I'm currently reading the documentation on how to contribute on Activity Watch and I am interested in helping you with the documentations :)

[ErikBjare]

@ArchaeotheriumSapienter Absolutely, go right ahead and make a PR and I'll happily review :)

[ArchaeotheriumSapienter]

If I may ask, is there any guideline that I should read or the Developer Documentation is enough? Furthermore, do you want specific formatting for the documentation? Like sphinx-style perhaps?

[ErikBjare]

@ArchaeotheriumSapienter No specific guidelines for docs, but do try and keep it in line with existing formatting (not sure what "sphinx-style" means here).

[8Dion8]

Hi! I'm interested in creating examples for visualising data outside of AW with matplotlib. Where can I discuss this?

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.