- Why are you hurry to commit? README.md is first official document,
which users from GitHub encounter. I think we should have more time
before publishing it. Otherwise, it can mislead users.
The question in the public posting is, "should this documentation
exist?", I was worried that people might have objections to that.
With documentation I don't expect it to be perfect on the initial commit,
and to have 3-4 follow up commits/replies for smaller things.
Also, back and forth full revisions of README.md make it difficult to
notice changes between the revisions.
I guess it puts a higher burden on some people who don't like objecting
to commits.
In the past I've seen the attitude of, "please get an initial version in
the tree, this is good enough and we can keep working on it in tree".
Getting the first initial document is hard / a different kind of task
than getting the wording perfect. I always discover a few mistakes the
very moment I commit.
I've been following this same policy for www.netbsd.org which has even
higher reach, but there it was extra justified as most people don't find
XML/HTML diffs legible.
I've received a small amount of feedback on IRC and was suggested to
post it on a more public list.
- Why do you mention only CVS repository although it is intended for
users of GitHub mirror? At least, the relation between CVS and
GitHub mirror should be elucidated. Otherwise, users get confused.
I'd like to mention the current canonical source. GitHub isn't the only
possible way that the source could be obtained, too.
In general a choice I've made here is to be very terse.
(In my limited UI/UX experience, we've primarily cared and benchmarked
how quickly users get the relevant information. The assumption was that
in an initial place like this, if users, say, take 30 seconds to figure
out something, we've lost a large percentage of our prospective users.)
- Why "VAX" and "M68k" are capitalized while "arm64" and "amd64" are
not? Why don't you use "aarch64" instead of "arm64"? How do you
choose options for build.sh (what happens if they don't have ~/obj)?
etc.
~/obj is created if it doesn't exist. ~/ should almost always exist as a
usable destination, which is the reason for this choice.
Perhaps I should clarify that it builds in ~/obj.
The choices are "hopefully the choice that will satisfy as many people
as possible":
- People who don't know which arch are the ones who look for amd64, and
it is a common choice too. It mentions the syntax for picking an arch.
- -j4 is a safe bet on many machines today
- I expected arm64 is more recognized as a name by humans.
- I've never seen VAX not capitalized. joerg suggested the
capitalization of m68k, but perhaps I misunderstood him.
IMO, tech-toolchain is not the most appropriate place for discussion.
Please send it to developers' internal list.
We technically have 'netbsd-docs' as the perfect list, but I was
afraid it won't have enough visibility to people who would object to
the existence of this documentation (disliking GitHub, disliking
markdown).