ArchStudio/DocumentationStandards

ArchStudio Documentation Standards

These standards have been approved by the ArchStudio Community Consensus Process.
Any changes must be proposed on the archstudio-dev mailing list.

This page documents standards for ArchStudio documentation. Documentation standards ensure a standard level of quality for ArchStudio documentation, ensuring that individual features (and the product as a whole) have adequate, up-to-date documentation.

Documentation Resources

The following are the documentation resources for the ArchStudio product. No new resources may be created or substituted for these without going through the community consensus process. There are two types of documentation resources: end-user facing and developer-facing. End-user facing resources are primarily intended for the consumption of ArchStudio end-users, while developer-facing resources are primarily intended for the consumption of ArchStudio developers and advanced users.

End-user facing resources must be updated with appropriate documentation before a feature is released in the official ArchStudio release. Features without specified documentation in end-user-facing resources will not be released. Conversely, features under development in branches must NOT be documented in end-user-facing resources until they are released. Proposed end-user-facing documentation should be processed through the community consensus process.

  • End-user-facing Resources
    • The ArchStudio product itself, as released on the Eclipse update site.
    • The  ArchStudio website.
    • The archstudio-announce mailing list.
    • Academic publications and technical reports.
    • The ArchStudio trunk in the Subversion repository.
  • Developer-facing Resources
    • The ArchStudio wiki
    • Preview versions of the ArchStudio website in the Subversion repository.
    • The archstudio-dev and archstudio-commits mailing lists.
    • Branches in the ArchStudio Subversion repository.

General Standards

  • All documentation should minimally be clear, concise, and written in grammatically and stylistically correct English.
  • All conventions of ArchStudio branding should be followed where appropriate, particularly on the end-user-facing resources.
  • If you notice an inadequacy or problem in documentation, you should either fix it or file a ticket.

Review Standards

  • All end-user-facing documentation should be reviewed and updated before each release (e.g., once per quarter).
  • Developer-facing documentation should be reviewed and updated opportunistically.
    • All tickets must be addressed in accordance with ordinary ticket-resolution policies.

In-Code Documentation

  • At a minimum, all public classes, methods, and members must be documented with Javadoc comments.

Metamodel Documentation

  • Metamodel artifacts (e.g., schemas) should be thoroughly documented.

Website Documentation

  • All tools must have their own documentation page or pages on the main website with illustrative screenshots.
  • All major features of tools must have their own documentation on the main website with illustrative screenshots.
  • Documentation on the website should be user-centric, explaining how end-users should use the tools rather than how they are constructed internally.
  • Website content should follow the established standards and templates.
    • Content should be restricted to fit in the 600px-width content area.
    • Navigation bar entries should fit in the 150px-width navbar area.

Tutorials

  • A Lunar Lander application should be the standard example used for tutorials.
  • TODO: Need to decide on standards for tutorials and assign people to work on this.