Missing Documentation Pages

[isidore]

Is there a documentation page that you would like to see?

Add the title of the page below in a comment. Also, please preference it with one of the following four categories:

1. Tutorial - Step-by-step guide to get started
2. How To - Recipe to solve a specific problem
3. Explanation - Theory and history around ApprovalTests
4. Reference - Description, lists, and statistics of ApprovalTests api

[isidore]

@Kurru requested ....

1 or 2
https://github.com/approvals/ApprovalTests.Java/blob/master/approvaltests/docs/Reporters.md#class-and-method-level

I found the documentation about the PackageSettings a little lacking. Specifically I had a hard time figuring out the best configuration for use with IntelliJ running my tests. The differences between the various reporters were unclear and I had to try a bunch.

Separately, using PascalCase for variable names seems unusual vs camelCase or even better UPPER_SNAKE_CASE.

For the record, we eventually found:

public class PackageSettings {
  public static EnvironmentAwareReporter FrontloadedReporter = new JunitReporter();
  public static ApprovalFailureReporter UseReporter = new QuietReporter();
  public static String UseApprovalSubdirectory = "golden_files";
}

[MichaelRWolf]

I'm too new to the documentation to provide specific examples of missing documentation, but there's a "code smell" that's feeling more relevant. I've chased lots of irrelevant and outdated documentation. I typically found better documentation, so the request here is to do some Document Pruning.

It could be as simple as adding a header...

This documentation is old, and preserved here only for historical purposes. See, instead: http:///newdocs.sample.com

There are lots of patterns that could work.

I got some great advice 15-20 years about website design:

Do not architect your site with the assumption that users start at the home page and navigate themselves to a page.
Most users "parachute in" by following a search result. As such, they have (almost) no context. The page they land on should answer 3 basic questions:
Where am I?
What's ineresting here?
Where can I go next?

I was reminded of this as I landed in lots documentation that was both related and disjoint... across time (10+ years), across repos, across projects, across designs.

I know that this message is more divergent than convergent. Maybe focusing on Jobs To Be Done (instead of docs to be polished) may be a helpful. Here are some of my early less-than-stellar starts.

• After following Emily's (amazingly wonderful) video on Gilded Rose, I took the opportunity to learn IntelliJ. It was a great way to learn. But somehow, everytime it needed to do a diff, it fired up Visual Studio Code. ;-) Some questions I needed to know along the way to getting it better (but not how I wanted it).
  • Why was it doing this? How could I get more visibility into it? Was this an Approval Test issue or an IntelliJ issue?
  • Once I figured out that it was something to do with a diff(1)-like program, I found the (overwhelming) list of options. Yeah for options! But I did not learn how to apply this knowledge. How do I configure the right diff(1) tool? How do I use meld(1) instead of VSCode as my diff tool? How is the diff tool related to a reporter?

I saw that Emily got a command to copy/paste that would do the acceptance. I didn't see that, so I manually renamed the file.

Time out! I'm feeling like I'm chasing an anti-pattern of trying to specify a specific problem by painting too many general pictures. I'd be happy to do "Individuals and Interactions" ;-). I'll cut it off here, and leave a "promise for a future conversation". Please feel free to engage me in finding som eway that my still-under-informed self can leverage my beginner eyes to this project....

Best,
Michael

[Chris-May]

Tutorial - Step-by-step guide to get started

I'd love this, and I'd love to help with this. I can get things going on my personal projects, but whenever I try to convince a team to use approvaltests, we run into an issue about configuring the default reporter.

I don't understand the configuration enough to help them. I have only showed approvaltests in the context of a kata because I don't know how to configure reporters for the CICD environment as well as each individual's context.

[MichaelRWolf]

@Chris-May - I'll bring this up in the Sunday work/mob session. It might be a good time to do so. The last session I attended (2 weeks ago), we were working on a new kind of reporter so I brought up my concern about my non-understanding of how they work. I had to leave before the mob finished the feature, but I think they were pretty close to getting it finished.

Would you be available for a Sunday mob/work session? (See: https://github.com/approvals/ApprovalTests.Python?tab=readme-ov-file#weekly-ensemble)

[Chris-May]

I’m not available most Sundays at that time. 😕

I’d like to make an exception, but I’m not seeing many opportunities in the coming weeks.