Documentation

From Dryad wiki
Jump to: navigation, search

Wiki Standards

Standards for documentation that appears on this wiki.

General requirements

Every page on this wiki should:

  1. Include introductory text describing the basic purpose of the page
  2. If the document is not current, include a statement about the status. This statement should include an overview of the revision history. Use the keyword "outdated" in the status description.
  3. Include appropriate headings. Typically, any section longer than one screenfull should have its own heading. The major headings on a page should use the 2-equal-sign markup, and subheadings should use 3- or 4-equal-sign markup.
  4. Link to other relevant pages
  5. Be placed in at least one category

When marking a page as outdated:

  1. Edit/add the status statement at the beginning of the page. Include a summary of the revision history, and the statement: "Status: This page is outdated and of historical use only."
  2. Move the document so its name begins with "Old:".
  3. Add the category Historical Pages.
    1. NOTE: We're not using a namespace for "Old", because MediaWiki won't let you move pages into a namespace.
    2. NOTE: pages in the WG namespace should not be moved to Old, since that would make them public. Just leave them as WG.
  4. Look for any pages that link to this page, and inspect the links. Some links may need to be updated to point to a newer page.

Requirements for technical features

For each technical feature, there should be a user-oriented feature page. The wiki page for the feature should:

  1. be linked from any appropriate places on the "main" datadryad.org site (e.g. "click here for help")
  2. be linked from the repository development plan (where the feature was first released)
  3. be categorized under the Help category and the Features category, as well as any other appropriate categories

Template for user-oriented feature pages:

Scope of this page -- one sentence!

== Overview ==
In plain language (preferably include bullet points) describe what the feature means for a typical user.

== Instructions ==
Step-by-step instructions, with screenshots highlighting the use of the feature.
This may include a workflow diagram.

== Technical Documentation ==
Brief list of links to technical documentation pages on the google code wiki or elsewhere.

== Design History ==
Link to any wiki pages or other resources used while designing the feature.




The technical documentation pages should be located in the Technical Documentation category. Template for technical documentation pages:

Scope of this page -- one sentence!

== Overview ==
In plain language (preferably include bullet points) describe what the feature means for a typical user.

== Usage ==
Detailed description of the feature's scope and how the feature is invoked.

== Configuration ==
Description of configuration options available for this feature.

== Workflow ==
A workflow diagram, indicating what pieces of code are active as the feature is used.
Include a set of numbered steps describing the workflow.

== Relation to DSpace ==
Indicate how this feature overrides or changes the default features in DSpace. Link to any relevant pages in the DSpace wiki.


Note: Some features implemented by @mire already have documentation in PDF form. Initially, we will link to these PDFs. Later, we may break them up into wiki pages.

Places and tools

Places where project documentation is created, developed and stored. The Dryad project requires creation of many documents. This section attempts to distill the software and locations in use, and their best uses.

(Yes, this list is a mix of file formats, applications, and locations. It's messy.)

  • Dryad web site
    • finalized documents that are needed by day-to-day users of Dryad
  • Dryad Development Wiki (see Standards above)
    • Anything that needs to be communicated publicly
    • Final versions of PR materials are on the Publicity Material page
    • Most documentation belongs here, but not documents that need to be kept confidential
  • GoogleDocs
    • For files on which multiple people are working, especially spreadsheets (because this is hard to do on the wiki) and anything that requires concurrent editing
    • Most useful while a document is initially being created. Some documents remain here, but others are exported to more permanent formats
    • For information that isn't public, but keep in mind that this isn't truly secure
    • It can also be used to privately share one or a handful of documents that aren't used for concurrent editing (e.g. PDFs)
  • Microsoft Word
    • The late stages of many formal documents (publications, grant proposals, etc.)
  • PDF
    • The final stages of PR and other documents that need to be widely read. (Many documents are transformed to PDF before placement on this wiki.)
  • WebDav
    • For the most private information
    • Only put things here if they need the security, because it is less convenient to use
    • It is appropriate if there is a large number of files and the person who needs them will be accessing the directory on a regular basis.
  • Dropbox
    • Mostly an option for backing up an individual's files
    • Not currently being used much for sharing and not everyone has an account, also not useful for concurrent editing
  • WordPress'
    • Stores completed blog entries (i.e., short-to-medium length time-sensitive news and PR pieces), as well as drafts of pending blog entries.


Storage of working drafts and documents

  • Dropbox
    • best for large files requiring collaboration
  • Google Docs
    • only works for the document types that Google supports

Presentations

  • PowerPoint

Mockups

Balsamiq

Diagrams

(still being discussed)

  • Creately -- Online. Excels at creating/managing connections between objects
  • PowerPoint -- Versatile. Doesn't support Linux.
  • Dia -- Free
  • OpenOffice Draw

Rejected:

  • OmniGraffle -- Mac only
  • Google Docs -- really doesn't do well for diagrams

Questions

  1. Do we want to keep curation manuals and software manuals on the wiki?
    • If so, any opinions about their organization and how to make them more prominent than all the other curation-related or software-related information on the wiki?
    • ANSWERS SO FAR: Software manuals will be generated from wiki content, using a list of pages that are included in each manual.
  2. What are preferences for working on shared files?
    • GoogleDocs seems to be getting the most use - is that what everyone prefers to use? Do people like and use Dropbox more than it seems? Are there other sharing practices that should be added here?
    • Dropbox isn't good for working on shared documents concurrently, but it does obviate the need to send around a copy of the latest version.
  3. Do we need to have the blog content backed up somewhere?
  4. How to best manage permissions, especially as the board membership changes?
  5. Where to store videos? On our wiki/website? On a more public space like YouTube?