This task is about documenting the process and materials that a contributed module or theme should provide to end users, including installation, usage, FAQ, samples, themes, snippets, and troubleshooting for a module. This documentation will serve as a guide to individuals wishing to document their modules.

For examples, please look at the documentation provided in http://drupal.org/node/206719.
http://drupal.org/handbook/modules/flag

This guide should contain recommendations for which pages should be included in a module's documentation, the page ordering, the recommended markup and layout for sections, as well as screenshot guidelines.

Relevant items include:

  • Installation - what items should be documented for each module, and what items are common to all modules (and thus to not need to be documented)
  • Basic usage - This should include configuration, where to find settings, permissions, where to find the in-module help, etc. Portions of this such as permissions, and location of configuration should be standardized as much as possible so that documentation between modules is consistent.
  • FAQ - guidelines for adding an FAQ to the documentation, what type of questions should be listed, when should items be explained inline, vs. moving them to a separate page
  • Sample usage - if applicable, provide a common use case of the module as an example
  • API documentation - If applicable show how to document the basic usage of a modules API
  • Sample snippets - If applicable, show how to style and include code snippets
  • Troubleshooting - determine if this section should be included, or come up with guidelines for when this section should be included, or what items are common to all modules, and should be documented elsewhere
  • Theming - determine how theming information for a contributed module should be documented, should only the most common use cases be shown, or should a list of all themeable functions be included?
  • Determine what other sections could apply for contributed modules or themes

All of this should be documented in our handbook somewhere with both guides as to what content should be included as well as what tags and markup should be used to style the documentation in a manner consistent with drupal.org documentation including screenshot guidelines, including what themes should be used, sizing and image format, as well as whether items should be uploaded externally, or to drupal.org.

Comments

mikey_p’s picture

mikey_p commented

I meant to include that the link to http://drupal.org/handbook/modules/flag is an excellent example of fairly comprehensive module documentation.

mikey_p’s picture

mikey_p commented
Status: Active » Needs review
ilo’s picture

ilo commented

+testing, I'd add that modules might include a functionality testcase at least in the documentation.

I think this gci issue is great!

dalin’s picture

dalin
he/him
Primary language English
Location 🇨🇦, 🇲🇽, 🌍
commented
Status: Needs review » Reviewed & tested by the community

This could bring some standardization to contrib documentation which might be nice for newcomers.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Um. We actually already have some documentation on how to document your contrib modules

http://drupal.org/node/161085

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Reviewed & tested by the community » Needs work

I really don't think this is a big project. Some tweaking of that page maybe...

mikey_p’s picture

mikey_p commented

Feel free to close this issue then. This issue isn't really about code or inline documentation for a module, but rather a guide for handbook documentation on d.o.

I've had a hard time finding docs in the handbook since the redesign, since things seems to be split between http://drupal.org/documentation/build and http://drupal.org/documentation/structure and I'm sure there are other places that have contributed module documentation as well.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Yeah, it's hard to find stuff. Sigh.

amye’s picture

amye commented

Despite the fact that it's kindof hard to find documentation, this is a well thought-out task.

Mikey_P, would you be willing to mentor this task?
(I'm circling back through the issue queue to clean stuff up.)

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Is it really a big enough task? It seems like all the existing page needs is a small bit of tweaking, and it's mostly there. See #5 above.

amye’s picture

amye commented

From my review of the tasks on GCI currently, we don't have a lot of tasks that really do fit the 'easy' category. I'd like to jump that number up, if at all possible.

1) That it'd take about 4 days, roughly, in between schoolwork.
2) Something that can be done without prior knowledge.

We have a few good Dmitrig01 tasks, and a few other challenging tasks, but not a lot of 'low hanging fruit' tasks.
If there's ideas about how to make this stronger, I'm happy to help add that into the task template.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

I'm pretty sure that we do not want someone with no prior knowledge of Drupal development setting the standards for contributors on how they should document their modules.

amye’s picture

amye commented
Status: Needs work » Needs review

I'm here to help Google Code In pull together. If you have suggestions about how to create tasks for documentation in Google Code In, that's what I need here. I'm not a docs expert, but this does look like a researchable task for a student with familiarity, if not a lot of prior knowledge.

I'm not trying to define a framework, but I need more help defining tasks that are going to meet the goals of the project and our involvement in it. Can you help me create a new task around documentation for code standards that fits the bill for this type of contribution?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Title: Create a guide for documenting a contributed module or theme » Clarify and complete the contrib module documentation guide
Project: Google Code-in » Documentation
Component: Documentation » Correction/Clarification

OK. I discussed this with amye on IRC today.

I think this particular task is an hour or two of work (editing the "how to document your contrib module" page) for someone who knows about Drupal contrib modules, so I'm going to move it over to the Documentation issue queue.

Meanwhile, I will look through the issue queues in the next day or two and see if I can set up some more easy to medium GCI tasks, and file them as separate issues

mikey_p’s picture

mikey_p commented
Title: Clarify and complete the contrib module documentation guide » Create a guide for documenting a contributed module or theme
Project: Documentation » Google Code-in
Component: Correction/Clarification » Documentation

Just to clarify this task was not meant as one requiring knowledge of Drupal development. This was meant to found out what organization and items make good *handbook* documentation for a contributed module. I assume they would be working with the handbook docs lead or team to make sure that they don't do anything crazy or detrimental to contributors. I can't find anywhere that anything like this is documented in the handbook, only a brief mention on the pages about inline module documentation, recommended that contributors use the handbook for additional documentation.

mikey_p’s picture

mikey_p commented
Title: Create a guide for documenting a contributed module or theme » Clarify and complete the contrib module documentation guide
Project: Google Code-in » Documentation
Component: Documentation » Correction/Clarification

x-post

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Did you look at
http://drupal.org/node/161085
?
I think it already has most of what you are suggesting, and could just use a quick update.

mikey_p’s picture

mikey_p commented

jhodgdon, I don't see any reference to the handbooks on that page. I feel like maybe I'm missing something, should contributed modules *not* be documented in the handbooks?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Here's the page that has this information:
http://drupal.org/node/188986

They need to be cross-linked and/or one of them should be eliminated.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

This page also has some incorrect information:
http://drupal.org/node/100748

We don't recommend putting contrib module documentation in a Contrib Modules section any more. Contrib module doc is added to various places, as the Handbook is by function/task rather than being separate for core/contrib.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Needs review » Active

I just closed
#792258: Define and document contrib docs best practices
as a duplicate of this issue. There's a bit of information there that may be of interest.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Here's another duplicate of this issue, with some relevant comments that should be addressed:
#748694: Unify documentation of best practises regarding README:s etc.

juan_g’s picture

juan_g commented

I agree that the contrib module documentation included in the Site Building Guide needs a bit more organization, however in my opinion just a quick, simple tree solution would be enough for now.

(...)

[Most of this post moved; see comment #25]

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Reorganizing the site builders guide is out of scope for this issue. Please file a separate issue...

juan_g’s picture

juan_g commented

OK, I've moved #23 to a new documentation issue: #1235970: Site Building Guide: General and topic-specific sections are mixed in a long list

colan’s picture

colan
he/him
Primary language English
Location Toronto 🇨🇦
commented

I'm confused about why the README.txt is a mandatory file.

If all documentation that should be in the file is either on the project page or the documentation page linked to by the project page, then why is this file still necessary? Isn't it redundant? It's duplicating data in multiple places. This makes things more difficult to maintain. There should be one authoritative source for this information. It makes more sense to have it on the web (on the project page and/or in the contributed modules section) where it's possible to use markup, where we're not limited to plain text.

juan_g’s picture

juan_g commented

why the README.txt

Many users read those files, so it's useful that they have this choice. And README.txt files are one of the sources that Advanced Help can use: #310819: index and show all INSTALL*.txt README*.txt files . See also, for example:
The README Manifesto
Drupal ImageAPI, ImageCache and why README.txt is important
...

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

One other thought: When someone downloads your module, they have your module files. They don't have your Project page, or the documentation you store in nodes on Drupal.org. They might, for instance, download the zip file, get on an airplane, and then try to figure out how to install or use your module. Without a README.txt (or maybe INSTALL.txt, etc.), they wouldn't have the information they need. Not everyone is connected to the Internet with high bandwidth at all times.

Another thought: as a module maintainer, I also find that I'm more likely to update the README (which is in with the code I'm modifying) then a remote doc page when I add features to the module.

tim.plunkett’s picture

tim.plunkett
he/him
Primary language English
Location Philadelphia
commented

I am firmly on the side of requiring READMEs. See #1151582: Update documentation to use field_get_items() for an example.

colan’s picture

colan
he/him
Primary language English
Location Toronto 🇨🇦
commented

I suppose it makes sense to have something off-line, but then why can it not be a README.html file? It still has the same mark-up as the web, plus it can be easily cut 'n' pasted from there. I prefer keeping the web as the master (rather than a text file), because of the added mark-up and linkability.

I can't think of anyone in the project-download situation that wouldn't have some kind of web browser locally, so he/she can still look at the documentation during a flight.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

colan: I think you could use a README.html if you preferred. I think most coder/developer types prefer to maintain a plain text file, but if you prefer to maintain an HTML file I don't see why we should object... Any other opinions out there?

arianek’s picture

arianek commented

I think a README in only HTML is also problematic, as if someone wants to read it as text (for eg. in their shell) it's going to be full of code. I'm thinking having both might be fine, but it's also pretty redundant then. So my vote is for either just README.txt or otherwise both.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Active » Fixed

This has had no updates in 3 years... so today:
- I added a section to https://www.drupal.org/node/161085 for a Handbook, with the items listed in the original proposal here. At least it's a start... https://www.drupal.org/node/161085#handbook
- I deleted the https://www.drupal.org/node/188986 (which had been archived and unpublished anyway) and redirected it to https://www.drupal.org/node/161085 -- it did not contain any info that wasn't on the current page.

I'm going to go ahead and mark this old issue fixed... we can reopen discussion if we need to, but let's use separate small issues to discuss specific targeted problems.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.