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.
-2
votes
0answers
44 views
NoSQL types drawbacks and advantages [closed]
what are the different advantages and disadvantages of each NoSQL type :(key-value,graph,document-oriented,column-oriented).
3
votes
4answers
297 views
NoSQL and BIG DATA
I am doing an internship on Big Data technologies so I am new to this area. My question is about the use of NoSQL in the Big Data architecture. Do we need always to use a distributed storage (like ...
5
votes
3answers
67 views
XML Documentation for IoC Classes
I'm working on an application that uses Inversion of Control to achieve loose coupling between the Data Access and Business Layers.
Having an ILoanApplicationRepository and a ...
35
votes
6answers
1k views
“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 ...
3
votes
3answers
189 views
Is it correct to exclude argument names from function prototypes?
I was recently creating a small technical documentation for an application. The document is to be used by newly hired programmers to get acquainted with the application. It is much friendlier than the ...
2
votes
3answers
196 views
UML diagrams for small projects
All of a sudden the need for proper formal documentation has become a thing in our organization. A lot of work I do are enhancements and addition to an existing system. Generally a quick fix or a new ...
3
votes
1answer
69 views
Does doxygen support templates for the HTML output?
I've documented my code for doxygen, but I don't want the default HTML it gives. I know I can customize it by providing custom CSS, headers, footers, etc. (like GNOME does), and how I can add common ...
3
votes
2answers
75 views
What's a good format for documenting hundreds of data feeds?
Several governments are starting to publish open data: datasets generated by the goverment, made freely available for citizens to use for value-added app development, analysis, and feedback. For ...
2
votes
2answers
125 views
How do I document a communication protocol on top of message queues and channels?
I'm working on a large project at the moment and I'm trying to document the communication protocol that sits on top of a message queue middleware.
The documentation is intended for another ...
0
votes
0answers
106 views
What is Highcharts using to generate their JavaScript api documentation? [closed]
The Highcharts 3.0 beta was announced today and there's a healthy discussion occurring on Hacker News. In the thread of comments about the release was a comment from Torn about what Highcharts is ...
2
votes
2answers
141 views
Is there any taxonomy/language to describe user interfaces?
I'm currently researching the options which I have, to build an 'Online Help System'. This system should offer the user information about dialogs - which consists mainly out of forms.
So my main ...
2
votes
3answers
99 views
How to document events?
Code documentation is usually related to a piece of code, be it small (method-level) or larger (class- or namespace-level). However, it is always about the inputs and the outputs of that piece of ...
5
votes
1answer
172 views
Are there any empirical studies about the effects of commenting source code on software quality, maintainability and developer productivity?
I am an advocate of commenting on source code and documenting software products. It is my personal experience and observation that working on source code that is rigorously commented has helped me in ...
5
votes
2answers
245 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 ...
2
votes
1answer
90 views
Is MSDN / Azure Active Directory information available in different formats?
I'd like to read the documentation of Azure Active Directory on my kindle (or similar device), but don't want to use "Print to Kindle" for each and every page.
Is the Microsoft documentation for this ...
1
vote
2answers
271 views
Deliverables in a software development project
Following a standard framework of project management, for a software development project we will provide deliverables (documents and software) at the end of each month :
My question is:
From May ...
15
votes
6answers
913 views
Can you claim that your product is fit for purpose when it uses OSS software which does not guarantee it?
I am working on a product for a client that must be valid and fit for purpose.
It's built on a LAMP stack (PHP/Cake), so there's GPL, MIT, PHP, APACHE licenses:
"AS IS" BASIS, WITHOUT WARRANTIES ...
0
votes
2answers
237 views
Software Requirement Specification documentation by professionals
I just wanted to know what is the significance of SRS(Software Requirement Specification) in programming? and what are the techniques used in preparation of an SRS .. also who writes the SRS.. is it ...
0
votes
0answers
54 views
Best way to find a co-author and a publisher for a book on an open source project? [closed]
This may be an odd question but I am the author of an open-source project and it is becoming clear that the only way to have real adoption is to write a full book on how to properly use the project. ...
1
vote
1answer
86 views
Splitting documentation between docstrings and sphinx
I'm using a combination of docstrings and Sphinx to document my Python programs. With Sphinx's autodoc, I can write a lot of documentation into the source as docstrings. Is there any standard for ...
1
vote
0answers
74 views
documentation of typescript code
my question is rather short:
How do I document typescript code properly?
I found out that for projects becoming bigger and bigger, it is important to look at a function and immediately know ...
1
vote
1answer
75 views
What is Context Diagram in a SRS?
I am learning how to write a System Requirements Specifications, and most of templates I have seen talk of a Context Diagram.
What exactly is a Context Diagram?
1
vote
2answers
121 views
Are there differences between Functionality and Functional Requirements
I'm writing some documentation in a project in a tool. In this tool of mine, and write in specific area, I have here use Case, Business Rule, N-Diagram Types, and Functionality and Functional ...
7
votes
4answers
420 views
Git-friendly spreadsheet format?
We're trying to move our project documentation process from Google Documents to a set of self-hosted Git repositories.
Text documents are Git-friendly enough, since we usually do not need any fancy ...
6
votes
3answers
158 views
How to refer to specific areas of code in documentation?
I'm about to leave a project, and before I go my boss has asked for me to document code (I've not documented very well). It's not a big deal, the project is not terribly complex. But I'm finding ...
4
votes
2answers
107 views
How to properly include field validation in a Software Documenation
I'm developing a software documentation in a project, and much of it are just CRUD or CRUD based functions. As you can imagine, a lot of the rules are constraints about fields validation, things like ...
2
votes
2answers
263 views
Describing requirements in SRS - use cases?
I do not have the access to the IEEE standard and information on the net are contradictory. Can I capture user requirements in SRS using use cases? Or I should keep use cases separate as they are more ...
2
votes
2answers
100 views
Wiki/markup in enterprise as documentation [closed]
Why it is less common to use wiki/markup in enterprise as documentation?
They use Word document instead.
Wiki/markup are in text format, which is version control friendly.
0
votes
2answers
607 views
What is the difference between technical specifications and design documents?
What are technical specifications? Are they the same as design documents. If not, what is the difference and some examples?
1
vote
2answers
201 views
Formalizing a requirements spec written in narrative English
I have a fairly technical functionality requirements spec, expressed in English prose, produced by my project manager. It is structured as a collection of UI tabs, where the requirements for each tab ...
5
votes
2answers
204 views
How does one read RFCs and similar documents?
RFC:
Request for Comments (RFC) is a memorandum published by the Internet
Engineering Task Force (IETF) describing methods, behaviors, research,
or innovations applicable to the working of the ...
2
votes
2answers
111 views
Questions to ask a 3rd party API provider [closed]
I'm due to meet with a developer/sales person from a new 3rd party resource we're about to start using. The main topic I'll be interested in, is their API as I will be the developer making use of it ...
5
votes
5answers
462 views
Is a functional spec a part of the System requirement spec?
I wonder, sources like wikipedia or templates I found shows that Functional spec is a part of System requirement documents. I always thought that SRD is just overall decsription of the system, with ...
5
votes
3answers
193 views
Commenting regular expressions
Are there any common practises for commenting the regular expressions: inline comments referring different part of RegEx or general comment for all expression?
0
votes
1answer
56 views
Is there such a thing as a specification-code framework?
I've been googling for a while and can't fathom why this doesn't exist yet.
By a specification-code workflow I mean a system which links code to it's specification. For example I could be looking at ...
-2
votes
1answer
76 views
SpecFlow/Cucumber - Documenting available steps [closed]
Our company is looking at implementing BDD in our .NET application. Specifically, SpecFlow.
We can foresee a large number of common steps being created ('Given a customer', etc), so what methods have ...
5
votes
2answers
168 views
What's a good length for Javadoc for a class that is say 800 lines long?
I'm doing a code-review on someone's code for class.
The class is about 800 lines long, contains a good dozen of functions but the description is like 1 line long.
I'm wondering, generally ...
6
votes
7answers
701 views
In what stage of development should comments be written?
I'm a student working an internship at a larger company, writing small business apps in C#. I've noticed that I don't comment my code as I write it. Rather, I comment my code when I'm in the ...
2
votes
0answers
125 views
Unreasonable Mono documentation [closed]
Why is Mono's documentation non-existent, in a form of XML-Documentation within the Framework (I'm talking about the Gtk and Gdk namespaces)?
Sometimes its way of operation is very counter-intuitive, ...
-2
votes
1answer
93 views
What should I aware of , when preparing a document of website for later maintenance use? [closed]
The development team has finished a website and my duty is to prepare a document so that other programmers can maintain the website with ease.
I have no experience in this and would like to ask what ...
2
votes
1answer
206 views
Why is it said that V-model introduces QA?
In several articles and books I learnt that "V-model introduced QA into SW development".
I would like to understand the point of such statement, as from my understanding, V model activities ...
3
votes
1answer
93 views
How to automate the API Diff document?
We can use doxygen to do the documentation, but how can I do the API Diff?
Any open source or free solution for that? Or I need manually prepare? Thanks.
6
votes
2answers
123 views
Seeking advice on system documentation
I have a rating engine (it is basically an algorithm) which when I started had no formal documentation. We have created a functional specification/decomposition which is our business level document ...
3
votes
1answer
213 views
A better JavaDoc? [closed]
The standard JavaDoc template(Doclet) didn't change much until the recent JDK7. In my opinion, JDK7 template only made it even more difficult to browse. I looked at several third-party doclets, but ...
6
votes
3answers
379 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
1answer
190 views
What schema documentation tools exist for PostgreSQL [closed]
MySQL has MySQL Workbench for designing and documenting your schema, and generates CREATE and ALTER scripts based on your design. We're looking at migrating to PostgreSQL in the near future, and we ...
8
votes
3answers
130 views
How to document experimental or incomplete APIs like @deprecated?
Is there a good term that is similar but different than "deprecate" to mean that a method or API is in the code base but should not be used because its implementation is not complete or will likely ...
2
votes
1answer
217 views
Lua & Javascript documentation generation
I am in the beginning phase of create a mobile MMO with my team. The server software will be written in JavaScript using NodeJS, and the client software in Lua using Corona. We need a tool to ...
1
vote
4answers
228 views
Is extensive documentation a code smell? [closed]
Every library, open-source project, and SDK/API I've ever come across has come packaged with a (usually large) documentation file, and this seems contradictory to the wide-spread belief that good code ...
2
votes
2answers
240 views
What norms/standards should I follow when writing a functional spec?
I would like to know what documents (ISO?) should I follow when I write a functional specification. Or what should designers follow when creating the system design? I was told that there was a ...
