7

I have the task to write the "technical documentation" for a software which I was developing. One reason or another I have never done this before, I do have experience with SRS, but this is something different. I am not sure whether the term technical documentation is the right one in the case (is technical manual better?). This is what needs to be described:

  • Where is it hosted
  • Used external services
  • Used languages and technologies
  • System requirements and supported browsers

Probably the document should include a reference who has information about the relevant credentials. In general I would also want to include a brief information about the used technologies (it is a web application using react/redux and WebAPI at the backend).

This appears like a pretty standard document for me, but I couldn't find what is its formal name (wrt software engineering). I would appreciate if you share what else would you include in these kind of documents? Is there a standard template/name for it?

Improve this question
7
  • 1
    see Why do 'some examples' and 'list of things' questions get closed?
    – gnat
    Commented Aug 9, 2017 at 8:56
  • 4
    Only the person who gave you the task can tell you what they mean by it.
    – Jörg W Mittag
    Commented Aug 9, 2017 at 8:57
  • 4
    You have only one half of the specs at hand: the what. Now you need the other half: the who. Are you creating a public document to put on your company's website? For a specific prospect? Client? An OEM developer with whom you have an NDA signed? Etc.
    – user44761
    Commented Aug 9, 2017 at 9:15
  • @JörgWMittag I am not so concerned with what they mean by it (which I will hopefully know soon), but rather whether this specific document type is well-known in software engineering. I have found a blog post describing this as Technical Manual (Writing a Software Technical Reference Manual)
    – djvuk
    Commented Aug 9, 2017 at 10:04
  • 1
    As @Tibo as commented, the who matters. According to the target audience, the level of details may vary.
    – Laiv
    Commented Aug 9, 2017 at 10:24

2 Answers 2

Reset to default
7

Usually, technical documentation is for other developers and/or administrators.

Imagine:

a) you are a new developer joining a software project. What kind of information would be useful to get introduced to the project.

b) you are an administrator who needs to maintain a software product. What kind of information would be useful (e.g. in case of errors, ...).

a)

  • coding / naming conventions
  • how to run / build / deploy the application
  • maybe an overview of the architecture
  • its place in the system landscape (which other systems interact with it)
  • ...

b)

  • Where the log file is located
  • How to configure the application
  • How to restart / deploy it
  • ....
Improve this answer
6

There is, alas, no generally agreed set of documents (and their templates) that all companies follow. Some may employ a project management methodology like SSADM, Prince 2, Agile etc, but even then, it can be highly customized to the business.

What you're really describing here is what you've already alluded to - it is a technical document. What you put in here really depends on the type of project. Even if you design yourself a specific template, the sections will vary widely depending on whether you're writing a console app, a web application or whatever.

Maybe try getting a steer to see what else has been written already and try to follow that.

If you're really a trail blazer, you'll need to keep a firm hand on the document as various audiences will want all sorts of stuff added so you need to be careful it doesn't suddenly morph into a training document or user manual etc.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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