Software Engineering Stack Exchange
Software Engineering Stack Exchange

Questions tagged [documentation]

Software documentation is written text that accompanies computer software. It explains how the software operates, how to install it, how to use it, and other resources for help.

Software documentation is written text that accompanies computer software. It either explains how it operates or how to use it, and may mean different things to people in different roles.

The types of documentations are:

  1. Requirements: statements that identify attributes, capabilities, characteristics, or qualities of a system. This is the foundation for what shall be or has been implemented.
  2. Architecture/Design: an overview of the software. It includes relations to an environment and construction principles to be used in design of software components.
  3. Technical: documentation of the code, algorithms, interfaces, and APIs.
  4. End User: manuals and online help for the end-user, system administrators, and support staff.
  5. Marketing: how to market the product, style guides, and analysis of the market demand.

Documenting source code can be helpful for anyone who might be reusing that piece of code. Many IDEs support *doc comments, such as Javadoc and PHPdoc.

633 questions
154
votes
50 answers

My boss wants a narrated line-by-line English explanation of our code

I have been specifically asked to give line by line (or as appropriate - for example, image by image, etc.) explanation or commentary which my boss wants to be able to read and follow. Since he is not a programmer, he can not follow the code so…
Billy Moon
  • 329
43
votes
7 answers

Should a rookie hint be mentioned in the documentation or not?

I was invited to review some code. I've never done that before and barely know the project. Thus I'm following the README step by step. I log everything. The README says in its "Quickstart" section: docker-compose up -d This line raised…
jjk
  • 545
43
votes
6 answers

"I", "We", or Neither in code documentation

I find myself writing (hopefully) helpful comments in code (C++) documentation of the type: The reason we are doing this is... The reason I use "we" instead of "I" is because I do a lot of academic writing where "we" is often preferred. So here's…
Alan Turing
  • 1,533
  • 1
  • 16
  • 20
39
votes
8 answers

Literate programming vs reasonably documenting your code

In a project that aspires from the onset to be maintainable across a revolving team of developers, what difference would it make to use literate programming against thorough commenting guidelines? The latter would imply: classes with explicit…
Quora Feans
  • 670
24
votes
11 answers

Why and how to write clear code comments and when will documentations be needed beyond code commenting?

I am learning programming on my own following standard programming language textbooks. I come from a math background. I learned C on my own, but never really got to the more advanced portions. I tried taking a coding course in college for CS…
Seth
  • 381
  • 1
  • 7
23
votes
7 answers

Release first or document first?

I've been working on a project for a couple years now, and I'm starting to gather a decent user base. I've created a project page with some basic documentation, but it's really not much more than a FAQ at this point. I know that I need to improve it…
cyberbit
  • 341
22
votes
8 answers

Should you document everything or just most?

It seems a bit of a controversial subject to document everything, including the "JavaBean" syntax of getters and setters for fields: People say its needlessly long and repetitive breaking DRY (don't repeat yourself), that the naming convention…
TheLQ
  • 13,580
18
votes
5 answers

What does your Technical Documentation look like?

I'm working on a large project and I would like to put together some technical documentation for other members of the team and for new programmers joining the project. What sort of documentation should I have? Just /// code comments or some other…
Rachel
  • 24,029
15
votes
8 answers

How much documentation is enough?

How much technical (for future developers) documentation is enough? Is there a ratio between hours coding and hours documenting that's appropriate? Papadimoulis argues that you should produce the least amount of documentation needed to facilitate…
C. Ross
  • 2,926
14
votes
6 answers

Why do so many libraries have no/poor documentation?

In a similar vein as the How can open source projects be successful without documentation about their design or architecture? question, I'm curious: Why are so many libraries so lacking in end user documentation? My view is this: Most everyone…
Billy ONeal
  • 8,073
13
votes
6 answers

How do I document my code?

I'm a hobbyist programmer (with no formal education) looking to start doing small freelance jobs. One of the things that hobbyist programmers can get away with that those with a "real" job can't is lack of documentation. After all, you wrote it so…
Brian Ortiz
  • 293
  • 2
  • 9
12
votes
9 answers

Code Documentation First?

Has anyone ever tried creating a complete code documentation first, before actually writing the code? I was thinking about this earlier because I thought it would help to write a concrete interface and would make sure your initial design wasn't…
ell
  • 966
12
votes
5 answers

Determining the right amount of documentation

Where I currently work the general approach is - avoid documentation as much as possible Only document if a different team will need it just for clarification, I don't mean code-documentation - this we do, I mean all the documentation surrounding…
Mithir
  • 1,339
  • 3
  • 13
  • 23
11
votes
3 answers

Writing High Quality Software Proposals

I've been reading over some proposals for software projects recently and I'm a little concerned by what I've seen. Often I feel that proposals have been rushed and/or poorly thought out. It's very possible that proposals don't need to look like a…
Desolate Planet
  • 6,058
  • 3
  • 30
  • 38
11
votes
1 answer

what kind of online technical documentation system would you recommend?

the goal is to have an online documentation system, with these major requirements: will be mainly used as an intermediate stage for the final technical docs of all our application (which will probably never get completed though :]). It would be…
stijn
  • 4,138
1
2 3 4