The Puppet Labs Issue Tracker has Moved:

This issue tracker is now in read-only archive mode and automatic ticket export has been disabled. Redmine users will need to create a new JIRA account to file tickets using See the following page for information on filing tickets with JIRA:

Feature #15528

High Level Feature #15403: Automatically produce & display useful documentation about a module

Show module's file as the module description

Added by Dominic Cleal over 3 years ago. Updated over 2 years ago.

Status:ClosedStart date:07/15/2012
Priority:NormalDue date:
Assignee:Melinda Campbell% Done:


Category:documentationSpent time:-
Target version:Better documentation and metadata
Keywords:readme, docs Affected URL:

We've Moved!

Ticket tracking is now hosted in JIRA:


The module description used on the Forge could be optionally populated from a README{,.md,.markdown} file stored in the module itself. For those modules that already maintain a README as part of the module, this will prevent the text on the Forge from becoming stale.

A radio button on the module edit page would perhaps allow the user to select between the two options – edit on the site as today, or enter/select a filename from within the module.

(This may be a subtask of #15403)


#1 Updated by Ryan Coleman over 3 years ago

  • Status changed from Unreviewed to Accepted

Thanks Dominic!

Just to recap:
Users should be able to make their README the modules documentation or choose to write something from scratch. Users should be able to modify this choice at any time.

#2 Updated by Ryan Coleman over 3 years ago

  • Parent task set to #15403

#3 Updated by Ryan Coleman about 3 years ago

  • Assignee set to Melinda Campbell

A supporting user story:

As a module author

I want the forge to use documentation already present in my content

So that I don't have to repeat myself

I’m keen on Dominic’s suggestion to offer this during publish and to always allow a user to split off from the automatically scraped description/README and specify something just for the Forge.

Assigning to Melinda to kick off the UX conversation.

#4 Updated by Ryan Coleman almost 3 years ago

  • Assignee deleted (Melinda Campbell)
  • Target version set to Better documentation and metadata
  • Keywords set to readme, docs

This is accepted into our next batch of work regarding documentation and metadata, which is scheduled next.

#5 Updated by Melinda Campbell almost 3 years ago

  • Assignee set to Melinda Campbell

#6 Updated by Melinda Campbell almost 3 years ago

We should add a line to the publishing modules doc ( explaining that when you upload a module, the module page will automatically display your README file.

#7 Updated by Ryan Coleman over 2 years ago

  • Status changed from Accepted to Closed

This shipped a while back.

Also available in: Atom PDF