I am trying to write documentation for a project and I have trouble finding information about list of documents that need to be written. I know there are Vision and Scope, User Requirements, Functional Requirements etc., but I haven't been able to find concrete description about which documents should be written and in which order.

What are documents are needed to fully describe a software solution? Is there some recommended order of writing those documents? Is there some book that describes this process in detail?

up vote 0 down vote accepted

There are a number of different books, often conflicting to some degree or another, depending on which methodology is in use, worse still some use different names for basically the same thing and some replace specific documents with other concepts. A lot also depends on the complexity of the system/project and the field that it is to be used in - with small simple utilities in non-critical areas expect less but for major projects &/or medical, military, space, aviation, etc. expect a lot more.

To wildly generalize for a reasonably complicated project in a reasonably formal environment expect:

  1. Concept document - used to sell the idea to the management. Without this you will not be able to get the funding to start
  2. Management Plan - Defines how you will work, Version Control, etc. may be skipped in some organizations/projects either includes the Quality Plan or references one.
  3. Budget(s) &/or Cost Analysis Documents, Staff availability, etc.
  4. Risk Analysis - Especially on Safety Critical Systems
  5. Requirements Capture Documents - not always done
  6. System Specification - What will the end product do in broad strokes.
  7. From this you should be able to write the system acceptance specification
  8. Interface Control Document - Essential if there is more than one subsystem or any external interfacing.
  9. Coding standards - if not already in place
  10. If there is a user interface then UX guidelines or design documents
  11. Detailed design documents, (stories in Agile).
  12. Unit Test Specifications/Story Acceptance Criteria
  13. Code & Test Reviews
  14. Developer Notes, mostly as comments in the code & readme files but possibly also in a Wiki.
  15. Unit Test Results
  16. Test Coverage Results
  17. Bugs & Enhancement suggestions, ideally a ticketing system is specified by the Management Plan.
  18. System/Integration Test Results
  19. Manuals
  20. Release Notes
  21. Marketing Materials
  22. Review documents on all of the above
  23. Lessons Learned
  24. Maintenance Proposals/Procedures
  25. Sun-setting or Decommissioning Documents

Expect all of the above to go through several iterations, (hopefully with releases).

You may well have additional documents such as Cyber Security Plans & Test Reports, various documents to meet company, compliance &/or regulatory requirements, etc.

A couple of things that I would urge you to do as you go on:

  • Release documents even though you know that they are probably going to change - this gives you a stake in the ground to work to and allows you to manage the changes that inevitably happen, (if you can compare Rev 4 with Rev 3 you can see what changed but if you don't have old copies...)
  • Get and use ticketing and version control systems in place ASAP.
  • 1
    "Get and use ticketing and version control systems in place ASAP." I recommend writing your documents in markdown or LaTeX since these are "plain text" sources as your code is and are best to be used with your SCM. markdown can even be rendered by the github frontend directly. – Timothy Truckle May 15 '17 at 8:33
  • @TimothyTruckle - Personally I would go for ReStructuredText and Sphinx-Doc but far to many companies & people are wedded to MS-Office tools. I have gone with the Americanisation of spellings suggested. – Steve Barnes May 15 '17 at 8:48
  • 1
    "far to many companies & people are wedded to MS-Office tools." Far too many think they are. Unfortunately most writers never get in contact with "plain text" based systems so they never experience the advantages for collaborated writing... – Timothy Truckle May 15 '17 at 8:56

Your Answer

 
discard

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

Not the answer you're looking for? Browse other questions tagged or ask your own question.