Add more fields to headers?

[Bartvds]

I think we should add some more (optional) fields to the headers (it has been mentioned before)

Some fields (names open for suggestion):

• Readme : {url} - url to regular documentation (site or readme on github)
• API: {url} - url to API documentation (if the project has it)
• Discussion: {url} - url to an open issue here on DT: so people easily coordinate and subscribe with github's watch feature. We could later rig Travis to add a comment if a PR or merge was done with a change for a linked file. (should do nicely as a low-tech notification list :)

[tomByrer]

Readme IMHO should be Homepage: {url} for their ( homepage.com | repo ) [in that order of precedence]. Repos move their docs from README to WiKi to http:docs.homepage.com all the time, so might be too much chasing the docs. You also have deep linking for API, should be good enough. This & the others are good ideas though!

[Bartvds]

@tomByrer Thanks for the input!

Note the existing format already has a link to the projects homepage (// Project: {url}). This is the nice front page (like http://gruntjs.com), or just the github repo for smaller libs.

The idea of this Readme: (or maybe Docs: or whatever) is to point to the general documentation (how to use the project) (like http://gruntjs.com/getting-started)

The API: would be specific API docs so you can quickly navigate to the official API description for more info or to source fixes if your defs seem wrong or outdated. (like http://gruntjs.com/api/grunt)

Maybe a Repository: field would help, to point to Github/Codeplex but I'm not 100% clear if that is actually useful: it is not really that relevant for definition consumers. (a case can be made that it would lead to the source code).

Also:

It cannot be helped if the projects move their content around. But then this fits the rest of the whole definition community: the data is only as good as it was on the moment it was written down.

[Bartvds]

Maybe we can add a Source: label <url> or Source: url (other name?) to link back to an external source where we got the definition file?

This could be cool when we import definitions,from external sources. We can even link a URI to the actual file? That'd be neat with a change detector script.

[vvakame]

I want APIDoc(API) and SourceRepo(Source) header. it is maybe useful for PR review. 👍

[tomByrer]

It cannot be helped if the projects move their content around

I agree; so it would be best to track as little as possible? Really it doesn't matter to me; just trying to save you some PR.