Create a README.txt template

+1 for this proposal on README.txt

I didn't realise modules should also include a CHANGELOG.txt, though core does, and conrtib should really follow core. So I'm not against this one either.

Cheers,
Stella

cough contribisnotcore cough... In the example above, INSTALL.txt from core is compared to a README.txt from contrib - that's like comparing apples and oranges.

• Most contributed modules do not need to re-explain common installation instructions again. They are already available here, where they can be updated and optimized once for all contrib modules, and can also link to advanced information for really novice users (f.e. common troubleshooting guide).
• Modules that require further installation steps can add them before or after the common steps. This way, users installing the module clearly see what is special about it.
• Developers should use their time to document information that is really important for the end-user, like configuration steps after installation, frequently asked questions, or troubleshooting issues. By using README.txt for these purposes, I was able to dramatically decrease support requests for some popular projects on d.o.

Given these arguments along with my experience in contrib, I cannot see a reason why this README.txt structure, layout and contents should be wrong. Morbus, if you know better, then start with fair criticism instead of complaining, please. ;) There is always room for improvement.

Daniel F. Kudwien
unleashed mind

LOL - sun, please. Suggesting "I've made more modules than you" as an indication of a stronger argument is entirely irrelevant (and yes, linking to my project page is indicative of that statement) - it's about as useful as me saying I've been a Drupal member two years longer than you, and run a site with chx anally ripping apart errors in modules. A five minute glance at admin_menu shows some stylistic "do what core does" errors I wouldn't have made already (@file needs to be one line, your "admin/settings/admin_menu" help needs a [p] around it).

Anyways. I'm not commenting on the content of your docs, but on its stylistic format.

• I'm not comparing "INSTALL.txt" to "README.txt" - I'm comparing the format of core's largest documentation file (being INSTALL.txt, because there IS NO README.txt) to the format of a module's largest documentation file (being README.txt, since there's little need for anything else). The apples and oranges comparison is apt if I were comparing content, but I'm not - I'm comparing formatting.

• I'll happily concede that "Most contributed modules do not need to re-explain common installation instructions again." However, note that your 6.x version of admin_menu links to a page that only describes Drupal 5 and 4.7 module installation instructions. When I, the module creator, and not the Drupal documentation team, am the primary method of support for a module, I would like utter control over all my documentation. (Yes, the instructions are nearly exactly the same for Drupal 6.x, but it's not very friendly when the first thing a user asks is "where's the install docs for 6?" and then blindly hopes that the 5.x version will work).

• "Modules that require further installation steps can add them before or after the common steps." Yes, exactly. No complaint there. Well, accept that your extra steps use two carets "Administer >> User management >> Permissions >> admin_menu" when a) core only uses one and b) the "common installation instructions" use only one.

• Why "-- SUMMARY --" and not core's format of "WORD\n===="?

• Why document something that doesn't matter, such as the "None" for "Requirements"?

• Why include HTML [code]/[/code] in the .txt file when it's plain text, not HTML?

Again, my key complaint is not the content of the documentation you've written, but rather, the /format/ of the documentation you've written. What was the logical reasoning besides choosing a different visual format to the ones seen and used within all of core's default text files?

Erm. Actually, Markdown supports Setext headers, and Setext has been around for quite a long time - as far as I can recall, it was one of the first defined text-file formats, in use as far back as 1992. "Any other syntax" tends to refer to wiki-based syntaxes which, due to the traditional lack of monospaced fonts in the textarea, right, navigated to a single character prefix. I'm not sure, however, that wiki-based syntax mentalities for our text files is the right approach. (With that said, I'd be perfectly fine on standardizing on Markdown or Setext for our .txt files.)

Why document something that doesn't matter, such as the "None" for "Requirements"? Simple: Because end-users ask this question in the issue queue otherwise."

So you promote using Drupal Handbooks to replace the install documentation, but not using Drupal core's own handling for module dependency (which a user CAN'T ignore) to replace a REQUIREMENTS header? Or were people asking about JavaScript based requirements?

If one wants to write an essay, one should create a HTML formatted documentation page on d.o instead. Plain text files should be used for basic communication only.

I disagree with this one - I'm of the mind that a module should ship with all the documentation that is required for its operation. One shoudn't be locked out of learning how to use a module if a) they're not on the Internet (working on a dev site on the plane), or b) drupal.org is suffering technical problems. I'm all for "Using bullet lists in each section. Keeping the information short and simple." though - I heartily agree that the chief barrier to documentation is /reading it/. The more concise documentation is, the better.

Regarding your proposed headings: CONTACT/CREDITS, in my opinion, should be merged into SUMMARY. The contents of CONTACT/CREDITS tends to be small, and doesn't really need its own section, and IMO, contact information should go near the top of the file (Nearly every "thing" I can think of always has contact info near the top, not at the bottom: emails, blogs, articles, etc.). And, I'm assuming that, if a heading doesn't apply, it is considered optional (ie., a new module wouldn't really have a TROUBLESHOOTING or FAQ, since there is no precedence yet)?

Forgot something.

Yeah, I'm not a fan of the use of [code]. Core doesn't use it for the SQL statements one must issue, instead relying on an indent and clear documentation on what to do with the forthcoming indent. I find that cleaner than adding [code]. I don't put a huge amount of weight in the "but an HTML preprocessor will understand it!" cos nothing like that has ever happened, and there are too many other things that an HTML preprocessor WOULDN'T understand (menu items, paths, function calls should be [code], headings should be H1, etc.). If we want the text files to be repurposed in other formats, then we should switch wholesale to a Markdown or Setext, where a backtick (`) would indicate code sections (and could also be used inline).

sun, I'm having a tough time "agreeing to disagree" - I'm not sure I can pick
out what you're really saying with all the (to me, at least) contradictions.

You disagree on a TOC, but the use of TOCs in these README's are not to indicate that the text file is "too large", but rather to give an overview of what is available in the documentation. Surely, as one who jests about his support queue, you should see some value in a user opening up your README and /immediately/ seeing that there is a "Troubleshooting" and "FAQ" section when, normally, said user would have to scroll through documentation that they may not, at the moment, care about.

As for the heading style, yeah, I'd have to agree: "it's just you" ;). Statistically speaking, the -- STYLE -- headlines are three lines (assuming two newlines before each section), and the other headlines are four lines (same assumption). Because the fourth line is a set of repeatable characters, which stretches across the length of the header (errors notwithstanding), there is more visual "weight" (how many times do you see ----------- in a file versus the 7-bit ASCII equivalent of an emdash: --), more horizontal whitespace (number of lines), and more vertical whitespace (the number of empty columns) than your variant (which, "it's just me", but gets lost for me quite easily). (And, to be semantically annoying, -- STYLE -- is equivalent to header style 2, which shouldn't exist without a header style 1, which your docs don't have.)

I would also contend that having a TOC increases awareness of headers.

I repeatedly need to look up the section I'm currently reading to know which part of the docs I am actually reading. You're really suggesting that your header format creates an increased awareness of which section someone is in? That's crazy. (I wouldn't even make that same argument about the alternative, and my preferred, header - there's just no basis to it.)

I find it also quite difficult to understand your "Yes" to my question about requirements. That totally threw me off - I didn't think you'd actually say "Yes"!. I'm just gonna have to skip over this one and say "Ok, I don't agree.". What I think we can agree on, however, is the need for a REQUIREMENTS section to detail, for example, third party software that can't be shipped with the module (non-GPL, jQuery libraries, GPL-stored-elsewhere, etc.); naturally, core has a REQUIREMENTS so no problemo there.. However, I'd like to make the use of "REQUIREMENTS: None" entirely optional - you can continue to use if it you'd like, but it's not something traditionally recommended. Agree?

As for CONTACT/CREDITS, how about we agree to call it CREDITS? This allows you to maintain your CREDITS as you see fit, but also allows me three possibilities: a) contact info in the SUMMARY; no CREDITS, b) contact info in the SUMMARY; previous maintainers, contributors in the CREDITS, c) CREDITS only. Since the SUMMARY is a free-form bit of text, there's nothing specifically stopping me from putting contact info there. This would keep us both happy, even though I 100% disagree on a few of your statements related to contact info.

I also disagree with your basis for the use of [code]. If you're basing the usage on "my users don't know where code begins or ends", then I contend that you're then assuming that your users DO, in fact, know what [code] is (which makes it even more confusing when you mix the use of [code] as a delimiter with other HTML elements, such as admin_menu's use of [param] in TROUBLESHOOTING, which also destroys any notion of an HTML preprocessor, since [pre], not [code], would keep the [param] in the context you're intending).

As for your comments about indentation, I call foul - you can never assume the user's indentation state: someone could be doing the silly CSS indenting mentioned in the other CSPO topic, the [param] you include (mentioned above) would almost always require some indentation, indenting doesn't matter to any of the places in which you'd copy paste code (CSS, HTML, PHP, JS), and if you're instructing users to modify your source code with custom PHP or JS, then it's actually a better service to let the indentation be wrong so that users can see exactly what they've changed from your raw/released code. You're really not saving the users anything whatsoever by claiming indentation as friendliness.

You agree that modules should ship with complete documentation, but continue to assert that one should "move the docs to the handbook", in cases of commonality (inferred from your "tricked you, docs aren't here, they're at [URL]" installation instructions) or length (as a counter to the [misunderstood] CONTENTS).

The point in a standardized README is not to "write better docs" - that's something that many other documents purport to teach. The point is to make a user's expectation about your README the same as everyone else's README: standalone and stylistically the same (visually, header-wise, etc.). Since the first README-style we can assume a Drupal user to read would be core's INSTALL.txt, all matching documentation should match those stylistic trappings.

I really like the idea of using a structured text markup - it could be Markdown or anything really (...I don't care which). This would allow us to easily write scripts to dynamically pull READMEs and INSTALLs into the documentation pages as HTML if desired, without needing to write a bunch of ugly regexps to deal with all sorts of exceptions to some invented 'standard' format.
[edit: reworded after a better reading of the above]

I've added a documentation page that takes a stab at standardizing README files, and provides a reference for beginner developers creating them for the first time. https://drupal.org/node/2181737