Taxonomy of information is important, the study around this is “information architecture”.
For a technical department, documentation comes in three real areas:
- Technical documentation - describes the inner-workings of the product
- Product documentation - describes the usage of the product
- Business documentation - describes the workings of the department
And one fake area:
- Project documentation - describes the current state of a piece of work that is making a change (either technically or organisationally)
EXPLAIN WHY this is fake
And broadly speaking, two types:
- Reference - documentation that’s permanent, of “living document” status, so evolves, but there is only one current version. Policy, process, strategy are good examples of “reference” business documentation, while most technical documentation is of the reference variety.
- Record keeping - documentation that’s created as part of a change programme. Project plans, minutes and reports are examples of this, which could be either technical or business-related.
Good reference documentation is:
- Current - write it in the present tense, make sure people are not wondering if this content is current
- Unambiguous - Avoid mixing up current with transitory issues eg don’t put migration instructions into the policies or processes
- Comprehensible - describe the intent of the doc organisation / IA and how to go about using it
- Discoverable - rearrange it as often as you need to, to enable exploration
Good record documentation is:
- Obviously record keeping - contains the date it occurred, the status of the document.
- Out of the way - arranged logically so it’s not confused with reference documentation.
- Write-once (eg evolved, but not updated) - if the record keeping isn’t helpful, and you don’t get something useful out of it, then change the format or the information captured, but don’t go back and try to change past versions.
Good information architecture (or doc organisation) makes things discoverable and good reference documentation engenders trust. These two things must be maintained, however, because .
Documenting the documentation
- If you don’t care, say so.
- Write in present tense
- Make it clear when last updated
- Write process as though it can be automated
- Explain rationale behind policy
- Diagrams good
- Important stuff first
- Advice / suggestions later + clearly marked as not-enforcable
- [Penalties] Careful about policing policy, too much written control will require lots of effort to check it’s being followed, and insufficient policing leads to people working without consquences, so some just do what they want anyway. It annoys follows of the rules + doesn’t stop bad behaviour
This is like the front pages that are just a collection of links
Making and tracking plans
- Project plans
- Health checks
- Risk logs
- Status updates
How you store this stuff will probably vary wildly by company and industry.
File-based formats like handbooks (Word, PDF) and info decks (PowerPoint, PDF) will still need to live somewhere like a file server.
Wiki-based formats like Google Sites, Confluence or Sharepoint provide baked-in hosting and editing features, and are probably the default intranet.
Programmatic formats like Doxygen, mkdocs or even static-site generators like jekyll and hugo need to store their source material somewhere (could be a file server or github) and their output somewhere else (probably a web server).
Structure and information architecture
Common types of information found in technology groups:
Product Delivery information
The pipeline from ideation to customer success. Yours might be called something else like “Technology”, but probably includes product people, UX people, developers, testers, designers, ops and more.
This site also represents the primary portal for discovery and exploration. This should be your “start here” site.
Start here pages need to include:
- Descriptions of the overall workflow from ideation to release and to
- How to use this site
- Pointers to other useful sites
Specific product delivery information (rather than meta info) should be included:
- The personae the business cares about
- Information over the domain split (do you have one core domain or is it * logically separated?)
- Coupled to above: how the organisation is arranged to accomplish work *
- Architecture & technical documentation (overview, diagrams, areas of pro * duct)
- Procedural (release, code review, working practices)
- Supporting system documentation (build pipelines, build systems)
- Policies about documentation! (doc-ception!)
- Non-function specific policies (? working hours ?)
- Chronicles - a place to keep records of events and other things that are going on.
Product Delivery will also be broken down further into the organisational model. So tribes and teams have their own areas which are neither functional or technical, but chronological.
Functional and discipline information
Functional or discipline information includes stuff that’s only relevant to that discipline, which is typically:
- Discipline-based events (CoPs, brown bags, etc)
- Any notes or WIP that doesn’t pertain to anywhere else yet
- Guides or playbooks
- Material that’s of interest, but not directly relevant to the product
- Things you want to share amongst your colleagues but doesn’t have a nice place to live
- Discipline-specific policy (could be pertinent to say Ops around overtime or on-call)
Example discipline list:
- Technology Leadership (?)
- Development Managers, Managing Developers, Developers
- Test Managers, Managing Testers, Testers
- Scrum Masters, Agile Coaches
- Operations, DBAs
- UX, UI
- Product Managers, Product Owners
Supporting and reference information
- This is mostly HR, IT, Facilities and other non-Product Delivery function and discipline information
Unit testing the IA
- Team improvement plans -> manager or tribe support area
- Team processes -> team area
- Charters -> team area
- If it’s discipline-specific (“here’s a handy guide to using this tech”), discipline-sites.
- If it’s because stuff is going wrong, and there’s no policy, then possibly part of Product Delivery, but review why there’s no policy.
- Retro notes -> team or tribe area under Product Delivery. Chronological notes.
- Project plans -> Product Delivery, scoped appropriately (if it’s everyone, it lives up the top level, if it’s one tribe, it lives down at tribe, etc)
Technical docs about the code and products
- Architectural precedents (eg decision to use framework X) -> top level product delivery
- How this app works -> product delivery, scoped by tribe into common technical area
- Coding standards -> if they’re genuinely standards, product delivery at top level or appropriately scoped by tribe, team or app. This is business reference not technical reference.
Appendix A: Business Documentation
- project plans
- service requests
- standard operating procedures,
- and more.
Appendix B: Policy, Process, Procedure
Policies are the guidelines or laws that drive the processes and procedures. (eg: highway code & road laws)
Processes are a high level view. The tasks within the overall process are identified. (eg: map denoting destination and starting point)
Procedures are the detailed steps required to perform an action within a process (eg: the turn-by-turn instructions to go to-from)