Ubuntu Wiki

Please check the status of this specification in Launchpad before editing it. If it is Approved, contact the Assignee or another knowledgeable person before making changes.

• Launchpad Entry: micro-manuals

• Packages affected:

Summary

Develop a series of concise, step by step instructions for getting a particular service up and running and include details like the Ubuntu version and the version of the software that was used, and additional references.

Release Note

Rationale

It struck me that one of the really nice things that would be good to have would be a set of concise manuals for how to set up a particular application (or set of applications) in a best practice manner.

• Micro-manuals

These would be concise, step by step instructions for getting a particular service up and running and include details like the Ubuntu version and the version of the software that was used, and additional references.

The aim of the manuals would be to capture a significant amount of details to allow a suitable competent system administrator to know exactly how a system had been configured, should the service need to be upgraded or changed.

After following the instructions, the end user should have a system which as some service or feature now set up in a completely known state.

In addition, it would inform package maintainers, exectly how their software is being installed and used, and allow them to upgrade their software or packaging to minimise the amount of additional configuration required (eg. sensible defaults and minimum required configuration parameters.)

In this way, the "Micro-manual" for a particular task should evolve over time to be a very minimal document.

The micro-manual should also be subject to some form of semi-formal release cycle, which ensures the highest quality possible. Eg. DRAFT -> UNDER REVIEW -> PUBLISHED -> (new release of Ubuntu) -> UNDER REVIEW.

Use Cases

Scope

Design

Contents

The following is a proposed 'standard' outline:

• Introduction
  • Statement of purpose (what does this manual describe)
  • Required Information (eg. IP addresses, hostnames)
  • Assumptions
• Installation
  • Required packages, versions and dependancies.
• Configuration
• Testing
• Backup and Recovery
• Appendices
  • References

Implementation

Examples

• postfix with pam/ldap
• Configuring mediawiki for an intranet site
  • Includes instructions for configuring local logo.
• Setting up openVPN
• Network print server
• SMB File server

See: ServerGuide for more possibilities.

Test/Demo Plan

Implement a single micro-manual to test design and the usefulness of the concept. eg. http://community.mawsonlakes.org/mediawiki/index.php/Category:Micro-manual

Outstanding Issues