Categorisation

Choosing a category

When choosing or creating a category, the following guidelines apply:

  • We should aim for longer pages with more content rather than a deep level of subcategorisation
  • Items are categorised by purpose, not by the type of data they represent
  • Top-level category names should aim to be a single word for scan-ability
  • There should not be more than one page representing one item - it should be clear where an item's documentation is found
  • Maintain a clear separation of subjects. For example, the Bitbucket page should be about Bitbucket itself, and integrating Jira with Bitbucket should be in Jira's documentation.
  • Pages should represent entities, not procedures

The Top Level Categories

The Top level categories should stay quite static and provide us with a high level organisation of content.

Redacted

Category Purpose
Culture and Social What it's like to work at Edmonds Commerce, and the atmosphere we like to maintain
Development Tools Any services, tools, programs and scripts that help developers do their job. These can be desktop software, online resources, command line tools, or frameworks for testing
Infrastructure Everything related to installing, configuring and managing our internal infrastructure
Languages Programming languages we work with, including tips, documentation and practices
Platforms Software Platforms we work on
Servers Tips on managing servers - especially client servers - including documentation for specific hosting companies
Support Documentation aimed at helping people we interact with, including EC staff
Temp Pages that are in various stages of completion, but not yet categorised

Culture and Social

What it's like to work at Edmonds Commerce, and the atmosphere we like to maintain

Each second-level item should represent one aspect of the EC culture

Development Tools

Any services, tools, programs and scripts that help developers do their job. These can be desktop software, online resources, command line tools, or frameworks for testing.

This has previously been one page per tool, but some of these such as Behat and Ansible have become too big. Those have been further subcategorised.

Each second-level item, be they pages or categories, should represent individual tools.

To Do

  • Move some of the post-receive-hooks content to Infrastructure/Clusters and Containers/Gitbare Bitbucket Mirror where appropriate

Infrastructure

Everything related to installing, configuring and managing our internal infrastructure.

That includes hardware, software, internal systems - basically anything that is running on our own hardware be that in the office or with external providers.

If EC owns it then it should probably go in here.

Second and Third Levels

Second Level Second Level Notes Third Level Notes
Clusters and Containers Anything relating to our Cluster/Container/LXC/Proxmox setup 4 third-level categories: Clusters for the cluster machines themselves, Containers for the LXC containers running on the Clusters or Desktops, Container Assets for the assets in our Snippets Library and Proxmox for managing our Cluster-hosted Containers
Desktops Staff members' desktop computers Configuration for desktop-level setup, be it OS- or hardware level, Desktop Environments for OS-level environment-specific items, Distros for items specific to a Linux Distribution. Installation for setting up of new computers. Software for any non-development-tool software we might run on desktops
Miscellaneous Servers Any EC-managed servers not part of the Cluster/Container setup Each third level item should represent an individual server that we manage
Other Hardware Any non-desktop, non-server hardware such as peripherals and phones Each third level item should represent an individual hardware type

Languages

Programming languages we work with, including tips, documentation and practices

In this category we discuss high level topics regarding working with specific languages.

Each second-level category should be the name of a specific language.

The third-level categories should represent coding standards, design patterns, best practices, tools, external reading, qualification study materials and anything else related to the language itself.

To Do

  • Move Languages/MySQL/MYSQL.md to Servers/Config/MySQL.md as it's more about the server than the language

Platforms

Software Platforms we work on

In this category we focus on specific platforms and frameworks. This can include testing frameworks. Where there is a major version difference, there can be a new sub category if so desired.

Inside the specific platform the contents will be similar to the languages sub category including coding standards, best practices, special moves, study material, tools and anything else.

(Confidential-Categories)/Recruitment

Documentation around recruiting new staff, including with regard to recruitment agencies

(Confidential-Categories)/Sales

Regarding the Marketing and Sales process - right up until the lead is converted into a client.

(Confidential-Categories)/Security

Our internal security policies - documenting which passwords are used, how we secure our online accounts and how to access out internal infrastructure

Servers

Tips on managing servers - especially client servers - including documentation for specific hosting companies

If something is not running on our infrastructure but we need to document how to install, configure or manage it then this is the category it should go into.

Second Level Second Level Notes Third Level Notes
Config Configuration applicable to client servers sofware like nginx, MySQL etc

Support

Documnentation for how our support systems work, including Jira, client documentation and this Handbook

Temp

A dumping ground for placeholder content, or content that's yet to be categorised