5
votes
5answers
234 views

Hyperlinked, externalized source code documentation

Why do we still embed natural language descriptions of source code (i.e., the reason why a line of code was written) within the source code, rather than as a separate document? Given the expansive ...
5
votes
4answers
498 views

Should user documentation include screenshots? [duplicate]

This question focuses on user documentation, not on code documentation. I just finished my software project, and the people I work for are expecting me to write user documentation, describing ...
-1
votes
1answer
66 views

What are the most crucial categories of content to organize into an internal developer portal in a large company? [closed]

I have been tasked with organizing all of the company's internal content currently spread around sharepoint, a markdown reference manual and confluence into a single cohesive and usable portal in ...
30
votes
2answers
1k views

Why aren't plain-text markup languages (like LaTeX or Markdown) more popular in the software development process?

I'm currently an intern at a government contractor and am getting the (obnoxiously unavoidable) feeling that Word is the de-facto standard in the software development process. Its binary format makes ...
5
votes
2answers
413 views

At what stage of a project should documentation be done?

I was assigned to fix some issues in a PHP project. Later on, I was asked to implement some new features, which I did. The project neither uses any framework nor does it use OOP. It lacks a proper ...
6
votes
3answers
530 views

Are XML Comments Necessary Documentation?

I used to be a fan of requiring XML comments for documentation. I've since changed my mind for two main reasons: Like good code, methods should be self-explanatory. In practice, most XML ...
0
votes
3answers
6k views

Are there any good, open-source change request systems? [closed]

I have a need to make a somewhat custom change request system (very high auditing requirements). Instead of completely reinventing the wheel I was wondering if there's an open-source change request ...
3
votes
5answers
849 views

How to make sure the application source code has a proper documentation for new programmers? [duplicate]

Possible Duplicate: How much documentation is enough? Do you know how the big IT company like IBM, Microsoft, or google make sure their application source code has proper documentation for ...
0
votes
1answer
522 views

How to structure process description documentation?

I'm writing a document describing process improvement recommendations. I have some best practices I've learned so far. I use those practices most of the time. But I suppose there are other ways to ...
8
votes
8answers
419 views

Moving from one man project to team project in the future. What should I be doing now in preparation and what can wait?

To elaborate I am interested in knowing what people think you need to put in place while still a one man project (team source control, documentation, builds etc) and what things don't need to be done ...
8
votes
7answers
3k views

What should you include in a development approach document?

I'm in the middle of co-producing a "development approach" document for off-shore resources as they ramp up onto our project. The most recent (similar) document our company has used is over 80 pages, ...
2
votes
2answers
879 views

Is there a software development methodology that is best suited for iPhone Development?

Which project management and software development methodology is best suited for iPhone Development? Are there any documentation templates available which documents an iPhone Development project?
3
votes
1answer
101 views

Javadoc for outsiders versus javadoc for insiders

When building an API for a customer, the public javadoc has to contain just what you want to show the customer. Which is a shame, as it the javadoc is also, in some ways, the obvious target for some ...
8
votes
5answers
596 views

I'm tasked with leading the documentation effort for an existing, entirely undocumented, software product - what resources are there to help me?

I'm a software developer at a technology company. I have been tasked with leading the documentation effort for the product I work on. The goal is to produce documentation internal to developer, and ...