pegram@kira.UUCP (Robert B. Pegram) (02/09/91)
From article <1991Feb06.015345.751@convex.com>, by rosenkra@convex.com (William Rosencranz): [All interesting Tex comments deleted - RBPIII] > files in manifest (all upper case :-): [large guffaw - considering Bill's usual posting style 8-) RBPIII] > > README describe what the program does, what the pieces > do, etc (so user/installer sees the "big picture") > INSTALL *precise* installation instructions, and the assumed > execution environment (cli, desktop, etc). don;t > make the user guess. and include any non-standard > environmental issues (like the termcap file cannont > have CR/LF line termination, just LF, which GNU > emacs port required at one time, and which i do > not ever recall seeing explained, for example) > BUGS we NEVER make misteaks (air the dirty laundry, > explain limitations, etc) > CHANGES change history or at least what's new in this post > XXX.MAN nroff source for a manpage (for nroff) > XXX.<section> ascii-formatted manpage (for humans, section 1 for > commands, 2 for sys calls, 3 for libs, etc, a la > BSD, if possible) > > and post the readme or at least an except before the uuencoded archive > so recipients know whether they need or want this post. this goes for > things archived but not posted as well. > > most software posted has much of this info, this just tends to make it > consistent. and yes, manpages are a unix-ism, but also a fairly common > method in this group for documenting things. note that i just posted the > latest nroff as well as a man(1) and a pager for man (manpager). and yes, > i would hope this would be in english :-). if we go thru the trouble of > getting something to run, and share it, we might as well spend an extra > hour to make it easier for people to install and use. [sure, why not] [...] > there, i feel better now... :-) > > -bill > rosenkra@convex.com > > -- > Bill Rosenkranz |UUCP: {uunet,texsun}!convex!c1yankee!rosenkra > Convex Computer Corp. |ARPA: rosenkra%c1yankee@convex.com I feel better too. I definitely second the motion. Only problem is... How do we get all of the Internet to adopt it? It's too good an idea to be just for STs.... comments? Bob Pegram pegram@griffin.uvm.edu or ...!uvm-gen!pegram