From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from fout-a3-smtp.messagingengine.com (fout-a3-smtp.messagingengine.com [103.168.172.146]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id AC48013FEE for ; Fri, 15 Aug 2025 19:47:15 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=103.168.172.146 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755287237; cv=none; b=qWVWJ1yzkPYBf3WjY20IOTEsGeXV5v7fSPgDmefC8XyH/wYzODuFMk9q1Y2wXCOegPtK75KHgwzSxKoc0fEFDjPsQBIaRPukB+5fRS3zdJIi5j0+XOUGXxzqjiZuDBEn3k/fOrzx7OXs/0sEWPXw7SemcP468pg6GKBOTmimIDo= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755287237; c=relaxed/simple; bh=YYyj8G221Mx4W0/1vZzA7gBS4wLB7ajyGlrCbe05CFk=; h=From:To:Cc:Subject:In-Reply-To:References:Date:Message-ID: MIME-Version:Content-Type; b=bNhNmWrqleL41fDuBpwbORpFlYO1+QbTTTTnXc1yAGyu78eFuNS37CIa/Fnmi7DvtZbrDNMaa4GTbwJjJj7Nbgkwq/qJaGfg0SmKiu/mhfxw6nxDoZ0WcR4ywEwQoxJhGXqh5psEzXbdl1elzWM0hF8BTKJ9e1YywJK0k18oeBU= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=pobox.com; spf=pass smtp.mailfrom=pobox.com; dkim=pass (2048-bit key) header.d=pobox.com header.i=@pobox.com header.b=XqndDldI; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b=Yp7BcmDx; arc=none smtp.client-ip=103.168.172.146 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=pobox.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=pobox.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=pobox.com header.i=@pobox.com header.b="XqndDldI"; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b="Yp7BcmDx" Received: from phl-compute-06.internal (phl-compute-06.internal [10.202.2.46]) by mailfout.phl.internal (Postfix) with ESMTP id 9E8B4EC00A7; Fri, 15 Aug 2025 15:47:14 -0400 (EDT) Received: from phl-frontend-01 ([10.202.2.160]) by phl-compute-06.internal (MEProxy); Fri, 15 Aug 2025 15:47:14 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pobox.com; h=cc :cc:content-type:content-type:date:date:from:from:in-reply-to :in-reply-to:message-id:mime-version:references:reply-to:subject :subject:to:to; s=fm2; t=1755287234; x=1755373634; bh=JTvTsdSPWS 80DpyCq9x9Lk9MV8KC/XBJMkFRP1pIKkI=; b=XqndDldILnCH0DakeZKej6v4fA Km+Kdxi2Qv9Ky6McZVvxdGuiv7/YX41iy3ld/GBTW4iE34d8WuPV+zRYCupLWdx1 LdYdScWUuU7kF+zdGnCmS4o2bl8+r6mFf1FUkz7KITyM2kaK2VNiUhVY3N2i3Nvo vHqB5kRBbcIpIR3aKWDi/JoS/zKkk3/O6SuW0IxxBXYVwMP3ZFhEQ1+GUMfFlCkV ygZemcNz+cleJ8ou/79BL7S6V1r0ycUi9wlpM8sLbjkXnqFKKefPuRLeNCXv1oW+ x4XBwOYb+fo9JaW7HGQsl6dVOvrVCXT4AyUn0hPFXx+vH+mSlcQmMBUr09UA== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:cc:content-type:content-type:date:date :feedback-id:feedback-id:from:from:in-reply-to:in-reply-to :message-id:mime-version:references:reply-to:subject:subject:to :to:x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s=fm3; t= 1755287234; x=1755373634; bh=JTvTsdSPWS80DpyCq9x9Lk9MV8KC/XBJMkF RP1pIKkI=; b=Yp7BcmDxthBuoVmqLgyaOhEYRYJ0w2541eAZ2wvVvnlijF7/1Tu AVHFn9ts99K7S5T/wvPvOuEyjkeL5CtX/08O9ijp1sU1ri/09u1PfovB7jyAdR7/ LVuuPHGne4nz5fdN3OviKxwc5m1WlmHNOAVS8tc8gDvwllyzd77SexOVR4yYqDba 99MhDZ7WG9Q9i2AurZomeC3I1AKSnIambOF3bLFm4tqsSDog57Sfy0cV+dlQUz7h setnLeFryp61cCyM05xAMb/wBM4MvbNujB63Wglz//RS8JQjsqO+zRXbWCQ9QdSq ncmvqrS3vN7WSRYjkbYqvsztLRZG8vg8wYw== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeffedrtdefgddugeegkeegucetufdoteggodetrf dotffvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfurfetoffkrfgpnffqhgenuceu rghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmnecujf gurhephffvvefujghffffkfgggtgesthdtofdttdertdenucfhrhhomheplfhunhhiohcu vecujfgrmhgrnhhouceoghhithhsthgvrhesphhosghogidrtghomheqnecuggftrfgrth htvghrnhepieekueefhfetvdfftdegfeekhfffgefgfeeivddugeffgfffffevvedvieel ffdunecuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhfrhhomhepgh hithhsthgvrhesphhosghogidrtghomhdpnhgspghrtghpthhtohepjedpmhhouggvpehs mhhtphhouhhtpdhrtghpthhtohepjhhulhhirgesjhhvnhhsrdgtrgdprhgtphhtthhope hgihhtghhithhgrggughgvthesghhmrghilhdrtghomhdprhgtphhtthhopehgihhtsehv ghgvrhdrkhgvrhhnvghlrdhorhhgpdhrtghpthhtoheptghhrhhishdrthhorhgvkhesgh hmrghilhdrtghomhdprhgtphhtthhopegsvghnrdhknhhosghlvgesghhmrghilhdrtgho mhdprhgtphhtthhopehjnhdrrghvihhlrgesfhhrvggvrdhfrhdprhgtphhtthhopehgih htshhtvghrsehpohgsohigrdgtohhm X-ME-Proxy: Feedback-ID: if26b431b:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Fri, 15 Aug 2025 15:47:13 -0400 (EDT) From: Junio C Hamano To: "Julia Evans" Cc: "Julia Evans" , git@vger.kernel.org, "Chris Torek" , "D. Ben Knoble" , =?utf-8?Q?Jean-No=C3=ABl?= AVILA Subject: Re: [PATCH v2 3/4] doc: git-add: make explanation less dry In-Reply-To: <886787d2-26b5-4451-a105-9ab522e38ad6@app.fastmail.com> (Julia Evans's message of "Fri, 15 Aug 2025 12:10:23 -0400") References: <886787d2-26b5-4451-a105-9ab522e38ad6@app.fastmail.com> Date: Fri, 15 Aug 2025 12:47:12 -0700 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain "Julia Evans" writes: > ... Then I ask them to give feedback on what's > confusing to them about the explanation or what questions they have. > > I do this because I find that often people who are extremely comfortable > with using the software (including me, which is why I usually spend so much > time collecting feedback like this!) can lose sight of what's confusing to an > "average user". Yes, you can lose your novice status and it is hard to take it back ;-) I agree with you that the next best thing you can do is to see how well folks who still have that status do. > And every time I'm part of a discussion about documentation for > an open source project it seems a bit strange to me for a group of people who > all already understand the concept to be discussing what would be clearest to an > "average user": surely the users themselves should be the judge of what's clear > to them! Yes, with one caveat, which is that you need to be careful to avoid throwing them into local optima. A simplified world view may make it look easier to swallow, but depending on the kind of white lies you throw at them, some of them they may have to unlearn to further understand the system.