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)
  • The user/developer split doesn't make much sense (kinda fixed in misc fixes to docs docs#53)
  • Many of the top-level pages should be subpages ("Running on Gnome", "REST API") (fixed in misc fixes to docs docs#53)
  • The order of pages don't make sense ("Installing from source" is way too far down, for example) (fixed in misc fixes to docs docs#53)
  • "Development" is a terrible page header (fixed in misc fixes to docs docs#53)
  • Avoid breaking old links (didn't find a nice way to do this...)
• Document where ActivityWatch stores data, cache, logs. (see: Where the database locate? #521)
• 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.
• Better interlinking in general (partially done in misc fixes to docs docs#53)
• Document where nightly builds can be obtained (see Nightly builds #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 (Implement reporting #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 Child categories do not depend on parent rules #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?)
• 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

• Add mention of ActivityWatch being "unsafe" on multi-user systems (see ActivityWatch doesn't behave well on multiuser systems #75)

Examples

• Add Examples page, which contains all other "Examples"-like pages ("Creating your first watcher", "querying data", parts from "Extending ActivityWatch")
• 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 (Add process and documentation for analyzing data outside of ActivityWatch #363)
  • Add example for reading into pandas (see: How to read the exported JSON in pandas dataframe? #339) (done in ActivityWatch/aw-client@9de8095)
  • 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]

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]

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.