On 10.10.2018 12:36, coypu%sdf.org@localhost wrote: > On Wed, Oct 10, 2018 at 11:31:43AM +0200, Kamil Rytarowski wrote: >> I'm in favor of plain text (README without .md extension) that is >> syntactically markdown compatible and in the same time not hyped with a >> currently popular format, file extensions or the currently popular set >> of extensions for Markdown (GitHub uses so called "Flavored Markdown", >> probably everybody uses a set of extensions). >> >> This plain text will be forward compatible. >> >> (Also Markdown is triggering some people, especially in the *roff >> circles. Additionally Markdown is not the only one supported by GitHub, >> there are rdoc, textile, org, creole, rst, asciidoc etc.) >> > > I don't have a strong opinion on documentation formats, other than > README.md carries a big benefit. I've mentioned that "introduction user > time is very important", and markdown helps me shave a small amount of > time by having [text](link), which allowed e.g. to insert an IRC webchat > link at no cost, which benefits people who are not familiar with > freenode on IRC. > > If GitHub tomorrow decides to only display text written backwards, I'll > rewrite it backwards without even questioning it. > >> I would reuse the existing project description rather than crafting >> something new from scratch with biased usage options. >> >> I've copy-pasted project description and stored it here: >> >> http://netbsd.org/~kamil/README >> >> It contains quick introduction, explanation what is the project about, >> building introduction, testing introduction and useful resources. >> >> I've omitted: biased command line for building the release, currently >> popular mirror and currently popular VCS. >> > > I am however very opinionated about the choices made here. > - The existing project description is very long. The second section here > is more characters than my entire README.md, without even accounting > for URLs. > I've made a similar change to the homepage: > http://cvsweb.netbsd.org/bsdweb.cgi/htdocs/index.html?rev=1.1982&content-type=text/x-cvsweb-markup > > - Similarly, you've spent 8 lines of text describing what tests are for, > and 5 lines of text on implementation details of our testing framework. > That kind of information is only relevant once I am interested in > copying or modifying the tests. > It isn't hard to reach information about test details once you know about > 'atf-run |atf-report', all our documentation is available as man > <command>, and man atf-run / atf-report cross-reference atf(7). > > - I realize that my own build.sh command is very opinionated, but I > think it's more important to have a command that you can copy and will > work or nearly work for many users than to be neutral. > > - The argument to dropping anoncvs makes sense if viewed from an active > mirror already, but I am considering the case where the mirror becomes > out of date (e.g. a fork). > AnonCVS isn't a personal preference, but the closest thing to a > canonical source that is publicly accessible. > The very day we change away from CVS I will happily change it :-) > > - Ideally, for most users, building will work right away. I don't want > to give them any indication it won't. > If we want to warn them that a C++ compiler is necessary, I would > prefer to do it via a quick sanity test in build.sh (or another > script) than pay the cost in documentation. > Similarly, I've made a change to warn if ./build.sh -x is used without > an appropriate xsrc. > > - I agree that a description of the source tree might be handy. I'd > rather do it differently and take advantage of whitespace where > possible, and only mention the directories more commonly edited, e.g. a > first try: > > sys/ kernel sources > sys/dev device drivers > sys/arch architecture-specific code > usr.bin/ sources for programs in /usr/bin > external/ software maintained outside of NetBSD (like the compiler) > > [man hier(7)](valid URL to man hier) includes more detail. > > The intention here is: > Omit usr.sbin/, bin/, sbin/ descriptions by mentioning only one of the > cases, the rest can be inferred. > tools/ is rarely something that people have to edit, so it's not worth > mentioning. > > And so on. > I hope that the additional details about why I make the opinionated > decisions help to explain why I have done things that way. While my > README.md is short, it went through multiple revisions and received some > feedback. I carefully thought about why to do things that way. > I would put biased quick introduction on wiki, on a page like http://www.openbsdjumpstart.org/ 10minute-start or similar and keep README for generic introduction what the source tree is about.
Attachment:
signature.asc
Description: OpenPGP digital signature