Documentation practices, the Trunk website, and the guide book

BGR360 commented 2 months ago

Before I say all this, I want to acknowledge the (often unthanked) work that the trunk team has done and continues to do to provide this tool for the community. Thank you! Open source maintenance is not easy.

The Problem

The issue I have is twofold:

As a new user of Trunk trying to do slightly more advanced things, it has been difficult for me to find the information I need.
As someone who wants to contribute new functionality to Trunk, I see no consistent practice dictating how I should document that functionality.

Problems as a new user

The website does not document all existing functionality of Trunk.
It is not obvious that there is also a guide, nor is it obvious why there is also a guide.
The guide contains more information than the website in some places, but also the website contains more information than the guide in some places.
It's easy for the not-so-careful reader (myself) to miss the link in https://trunkrs.dev/configuration/ that points to a complete example Trunk.toml, leaving them thinking that you can only configure a few things like a proxy.
On several occasions I have had to read the source code to figure out whether or not Trunk is at all capable of doing a particular thing.

Problems as an aspiring contributor

There is no guideline in CONTRIBUTING.md for when, where, or how to write documentation.
The existence of multiple different documentation sources makes me confused about where to put my new documentation

Next Steps

Here is what I would like to see as both a user and contributor:

1) Make it clear whether the website or the guide is the authoritative documentation resource.

If it's the website, then get rid of the guide and put all of its information in the website. This would be my preferred option.
If the guide is supposed to be the one authoritative source, then make that very clear on both GitHub and the website.
Alternative: generate the website contents from the guide, or vice versa.

2) Paste the example `Trunk.toml` into the authoritative documentation source's "Configuration" page.

I believe this is possible with mdbook. Then users do not have to travel to the GitHub to see what is possible to configure, and they have no chance of missing the GitHub link like I did either.

3) Make a policy for how to document new functionality, put it in `CONTRIBUTING.md`, and enforce it in PRs.

Developing such a policy does not happen overnight, and it can improve over time. But having anything at all will both lower the bar for contribution and improve the quality of the documentation.

9SMTM6 commented 2 months ago

It's easy for the not-so-careful reader (myself) to miss the link in https://trunkrs.dev/configuration/ that points to a complete example Trunk.toml

I do have to agree on that point. AFAICT this is the only place where all attributes are defined. Its fair enough to have that in the repo, where it can be tested, and where contributions can easily add new fields. But the documentation doesn't specifically say that its the only complete 'reference', and having it included inline in a paragraph, alongside stuff such as links to external projects etc, occasionally it took me a while to find even when I knew what I was looking for.

Re. Point 1. I think it would be good to declare an authoritative source, and ask contributors to add to in Contributing.md (Point 3). When it comes to unifying these, it would sure be great, but not required at this point, IMO.

ctron commented 2 months ago

I completely agree. The idea was to move away from the documentation in the website, and move to the guide instead, as it allows for a more complex documentation.

I'd like to avoid breaking existing links. So what that would require, are some redirects from previous pages to the guide. Not necessarily to the matching page, but at least to the guide in general.

I'd really appreciate any help on this.

trunk-rs / trunk