Missing Documentation Pages #135

Activity

1. isidore commented on Feb 19, 2023

   

   isidore

   on Feb 19, 2023

   MemberAuthor

   More actions

   @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";
   }
   
2. MichaelRWolf commented on Feb 20, 2023

   

   MichaelRWolf

   on Feb 20, 2023

   Contributor

   More actions

   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
3. Chris-May commented on Dec 26, 2024

   

   Chris-May

   on Dec 26, 2024

   More actions

   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.
4. MichaelRWolf commented on Dec 27, 2024

   

   MichaelRWolf

   on Dec 27, 2024

   Contributor

   More actions

   @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)
5. Chris-May commented on Dec 27, 2024

   

   Chris-May

   on Dec 27, 2024

   More actions

   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.
6. JayBazuzi

   added

   collector

   on Jan 4, 2026