1. Wiki
  2. /Computer Science
  3. /Technical writing

Technical writing

CIO - Chief Information Officer

In recent years it has become increasingly understood that knowledge limited to just business or just IT is not sufficient for success in this role. Instead, CIOs need both kinds of knowledge to manage IT resources and to manage and plan "ICT, including policy and practice development, planning, budgeting, resourcing and training." Also, CIOs are playing an increasingly important role in helping to control costs and increase profits via the use of ICT, and to limit potential organizational damage by setting up appropriate IT controls and planning for IT recovery from possible disasters.

Resources

  • Ask HN: Examples of good technical writing?
  • Ask HN: How to level up your technical writing?
  • An Engineer’s Best Tips for Writing Documentation Devs Love
    • don't tell anyone anything is simple
  • Technical Writing for Developers
  • Design Docs at Google #design-docs
    • purpose:
      • Early identification of design issues when making changes is still cheap.
      • Achieving consensus around a design in the organization.
      • Ensuring consideration of cross-cutting concerns.
      • Scaling knowledge of senior engineers into the organization.
      • Form the basis of an organizational memory around design decisions.
      • Acts as a summary artifact in the technical portfolio of the software designer(s).
    • structure:
      • Context and scope
      • Goals and non-goals
      • The actual design
        • System-context-diagram
        • APIs
        • Data storage
        • Code and pseudo-code
        • Degree of constraint
      • Alternatives considered
      • Cross-cutting concerns
    • 10-20 pages, 1-3 pages mini-doc also possible
    • lifecycle:
      • Creation and rapid iteration
      • Review (may be in multiple rounds)
      • Implementation and iteration
      • Maintenance and learning
    • considerations:
      • Are you unsure about the right software design, and would it make sense to spend upfront time to gain certainty?
      • Relatedly, would it help to involve senior engineers, who might not be able to review every code-change, in the design?
      • Is the software design ambiguous or even contentious such that achieving organizational consensus around it would be valuable?
      • Does my team sometimes forget to consider privacy, security, logging or other cross-cutting concerns in the design?
      • Is there a strong need for documents that provide high-level insights into the design of legacy systems in the organization?
  • Writing docs well: why should a software engineer care?
    • building shared understanding
    • tool for thinking
    • write to have influence in larger organizations
  • The Ultimate Guide To Software Architecture Documentation

RFCs / RFDs

Templates