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