Consolidate in-repo documentation

[djmitche]

This moves all of the in-repo docs (those which are not on taskwarrior.org) into doc/, organizes them with some READMEs, and eliminates some redundancies and incorrect information.

I'll follow up with another PR to move taskchampion/doc into doc/devel/taskchampion. This PR already has enough moving / editing / deleting!

Refs, but doesn't fix, #2868.

[ryneeverett]

I would think documentation changes like this would be safely included in your "implied powers" to integrate taskchampion. I'm guessing you want core contributor approval due to changes to the development docs (branching model, coding style, communication channels, etc). But it seems to me that your changes in these areas do not impose a change so much as reflect the status quo. More review is always good but I wouldn't let that hold you up for too long.

[ryneeverett]

I'll follow up with another PR to move taskchampion/doc into doc/devel/taskchampion.

Looking forward to this. We could also remove .github/workflows/publish-docs.yml. (I just noticed that github pages don't seem to be enabled so it's kind of pointless at the moment anyway.) Or were you thinking of turning the whole doc/ into an mdbook? Not sure what your vision is but I could probably help if there's anything non-trivial to do.

[djmitche]

What we have is:

• Docs on taskwarrior.org -- user docs, including some other GBF projects (markdown)
• doc/man -- man pages (troff)
• doc/devel -- developer documentation (RFCs and an extended contributing guide) (markdown)
• taskchampion/docs -- developer documentation for TaskChampion, and installation instructions for the sync server (markdown / mdBook)
• https://docs.rs/taskchampion/latest/taskchampion/ - Rust API docs, for embedders of Taskchampion

I don't really have a vision! Here's my thoughts:

• I think mdBook creates good, readable docs that are easier to read and navigate than raw markdown files in GitHub.
• I have a vague preference for including user docs in the repo, rather than GothenburgBitFactory/tw.org, because it's easier to change those docs alongside code changes. But moving it is a lot of work with small reward.
• I am inclined to move Taskchampion out to its own repo (e.g., GothenburgBitFactory/taskchampion). There are a few reasons:
  • The build-system integration is not great, and I think doing better would require invoking rustc directly from CMake, which would lose a lot of the Rust-y niceties of cargo and make this more like "some Rust code in a C++ app" than "a Rust library with a C++ CLI"
  • Splitting up CI for the two would help focus our attention -- the dependabot alerts are obviously all for Rust!
  • Separate repos would help to encourage a nice clean isolation between the two, so Taskchampion stays useful for non-Taskwarrior embedders instead of growing Taskwarrior-specific APIs.

None of those are terribly strongly-held convictions. What are your thoughts?

[ryneeverett]

I basically agree with all that, including the conviction level. I've split off the question of splitting the repo to #3187 and the discussion of the docs consolidation to #2868.

[lauft]

@djmitche I have no opinion about the Taskwarrior/Taskchampion relation, so I can only comment about the documentation, mainly with the intention to keep the structure/"look and feel" similar between Taskwarrior and Timewarrior for the users.

I have no experience with mdbook, but with Timewarrior, I have changed the man pages from troff to AsciiDoc, which I then can copy/sync with ti.net (my vision here is to do this automatically with every release). With this I can use timewarrior.net for the documentation of the current release.

As a rule of thumb, I would put anything stable on the site, anything volatile into the repository... 🤔