Page MenuHomePhabricator

Discuss documentation metadata
Closed, ResolvedPublic

Description

Metadata helps build context around documentation and makes docs easier to read and maintain. As part of defining accuracy criteria for key docs, we want to apply a set of consistent metadata. The purpose of this task is to discuss which fields to include.

Some ideas:

  • Last updated: Provides a quick way to see when the last edit was made to the page and by whom. Can be automatically populated by MediaWiki. (See Template:Last updated) Acts like a quick preview of the full history page.
  • Status: Free-form field to indicate the status of the page (WIP, draft, versioned, collecting feedback, etc.) This is something I rely on a lot with temporary docs, such as Google Docs. I've experimented with using a page status field on wiki in the Architecture Repository, but haven't ended up using it very much. Traditionally, page status is indicated by a series of banners (draft, outdated, etc.) or inferred from the page history. This would be more explicit and consistent, but still subject to falling out of date.
  • Steward: Although it might not be possible to find a team or individual to list as a maintainer for every key doc, I think an "Adopt this page" or similar link would be just as valuable to our overall docs goals. Andre and I discussed that "steward" was less strong than "maintainer", which might discourage people from contributing.
  • Type: The page's content type (overview, tutorial, etc.), linked to information about and criteria for that content type
  • Tags: I'm conflicted about this one. I think we need to think through specific examples of what would be included here and how it would differ from the existing category system
  • [Add ideas here!]

Event Timeline

Random opinions and thoughts:

  • Last updated might make some people think "Last reviewed" which it is not?
  • Status: I'd assume by default that the status is fine unless otherwise being told (templates obsolete, deprecated, outdated, draft, etc)
  • Tags: IMHO this partially duplicates categories (which I personally consider a mess and would not recommend to anyone as a way to find content)

Last updated might make some people think "Last reviewed" which it is not?

@Aklapper that's a good point. Is the actual date that the page was last reviewed more meaningful? Do you think there's a value in the autogenerated "Last updated" date?

As a result of our discussion, we determined that "last edited" and "maintainer" make the most sense here. However, I'd like to consider how we can incorporate this information in a way that doesn't duplicate the history view going forward.