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.
|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
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.
- Move some of the post-receive-hooks content to Infrastructure/Clusters and Containers/Gitbare Bitbucket Mirror where appropriate
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|
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.
Servers/Config/MySQL.mdas it's more about the server than the language
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.
Documentation around recruiting new staff, including with regard to recruitment agencies
Regarding the Marketing and Sales process - right up until the lead is converted into a client.
Our internal security policies - documenting which passwords are used, how we secure our online accounts and how to access out internal infrastructure
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|
Documnentation for how our support systems work, including Jira, client documentation and this Handbook
A dumping ground for placeholder content, or content that's yet to be categorised