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
3answers
571 views
How should I document a Python script?
I have a couple of Python modules that are meant to be run as scripts. How should I write the docstrings at the module and function level to make it clear how to run and use the module?
6
votes
2answers
1k views
Backend programming portfolio
For most of my development years I have been a Java backend developer, mostly for web applications. Usually for regular jobs I have described my duties in previous ones during the interview, expanding ...
6
votes
2answers
308 views
Are there any C API explorers/browsers out there that include the GNU C Library methods and data structures?
I am looking for something similar to the Java API documentation, but for the GNU C Library.
I am trying to develop a simple server/client Sockets program but I keep getting lost in the different ...
12
votes
6answers
613 views
Why do so many libraries have no/poor documentation?
In a similar vein as the Why do many open source projects have no documentation about their design or architecture? question, I'm curious: Why are so many libraries so lacking in end user ...
3
votes
1answer
614 views
How do I document the architecture of an existing application? [duplicate]
Possible Duplicate:
Methodology for Documenting Existing Code Base
What is the best format/setup for an architecture document? That is, the document that comes out of brainstorming an idea ...
21
votes
13answers
2k views
When do you start documenting the code?
Some friends and I recently started a medium-size project. We already covered the design part (at least the first attempt) and now we are moving into coding. We already have implemented some objects ...
7
votes
11answers
803 views
Does searching documentation and samples look bad?
I am starting a new job in a company with many developers and media people, the layout of the place is open with computers around a skinny oval,
I have worked in small teams and programming embedded ...
4
votes
4answers
2k views
job handover checklist [duplicate]
I have resigned my old employer to start a new job, and I need to prepare a handover [documentation to be taken by some new employee that haven't arrived yet, and would be some weeks from when I go to ...
1
vote
3answers
130 views
Documentation: What is “appropriate” when expressing a valid range for a parameter?
What is the appropriate method to describe a valid range of a parameter in the documentation of code? Obviously long-form documentation (white papers, API documents, etc) can be more verbose than the ...
4
votes
3answers
603 views
What wiki/document system do you recommend for knowledge-management?
I'm founder of a web-site called Now.in. I wrote all programs by my-self at first. And we are going to run a start-up company. More people will soon get involved. Some know-how/overviews only exist in ...
28
votes
3answers
766 views
Origin of “Readme”
When did people start writing Readme files?
It seems that pretty much all programs have this file, regardless of the format.
Is there any documented first use of this document?
5
votes
4answers
421 views
How much documentation should a client expect from a one-man team?
I work for a small electronics and support software company that just recently got a contract with a large company that's very strict on documentation (I do the support software, essentially Windows ...
7
votes
5answers
393 views
My manager hates documentation in our large project. What should I do?
I am working in a small team on a large complex software project. I want to document all requirements, but I've been told by my manager that it is waste of time.
I have tried the same with design ...
6
votes
3answers
783 views
Documenting a REST interface with a flowchart
Does anybody have suggestions on creating a flowchart representation of a REST-style web
interface? In the interest of supplying thorough documentation to co-developers, I've been toying around in dia ...
0
votes
1answer
148 views
on the dichotomy between internal and external documentation
For what kinds (size, complexity, scope, user-base, etc.) of APIs (or Applications) -- the separation between internal and external documentation is good (or necessary).
Internal -- that which is ...
3
votes
4answers
296 views
Documentation tool in one “simple” file?
Is there a tool like AsciiDoc or reStructuredText that is simple enough, like a standalone Python file, to be embedded in the repository of the associated project I'm writing documentation for? Assume ...
7
votes
1answer
346 views
How to document an algorithm properly with sample data?
I am wondering what should an algorithm documentation contain? Can't locate a proper guideline to follow. I have in mind to include
summary of the algorithm
description of the algorithm
flowcharts
...
2
votes
1answer
354 views
Open Source Web-based CMS for writing and managing API documentation
This is a question that have somewhat been asked before (i.e.: How to manage an open source project's documentation). However, my question is a little different because:
We're not developing open ...
6
votes
4answers
456 views
How to manage an open source project's documentation?
I am the creator of a growing open source project. Currently, I'm becoming frusterated trying to figure out the best way to manage documentation. Here are the options I have considered:
HTML Website
...
0
votes
2answers
119 views
quick prototyping in project design & development
i'm currently working on a project in my spare time (mostly 3-4 hours from monday to friday, and up to 6 hours on sundays) and i've found redmine very useful to hold a record of development tasks.
...
3
votes
2answers
89 views
What can I use to generate API documentation with my custom formatting?
I want to automatically generate documentation for a java project, but I'd like to have my own custom styling for it.
As an example, take the stackoverflow api (method description page), can that be ...
1
vote
2answers
145 views
Would you keep convincing your management some better practices if he keeps screwing things up
My manager, an enthusiastic programmer, is full of good energy to program. But he has a ... habit were he will be negligent in meetings if he can't understand the issue or argument. As a result, he ...
0
votes
1answer
184 views
Usefulness of Javadocs with unit testing?
I am sure some else has experienced the problem of documentation regarding unit tests. I was wondering if anyone has used javadocs with their unit testing to generate their own internal javadoc files ...
144
votes
29answers
7k views
Humor in Documentation
Is a small amount of lighthearted wording or humor acceptable in source code documentation?
For example, I have an algorithm that has a message hop around a graph (network) until its path forms a ...
1
vote
2answers
984 views
How do I write a software product definition?
I would like to learn how to write a software product definition. Therefore I am looking for online materials or books which would help me to learn more about this topic. I would like to learn, for ...
8
votes
4answers
799 views
How can open source projects be successful without documentation about their design or architecture?
I want to improve my programming skills by studying famous open source projects, but I find it is easy to get lost by just jumping into their source code.
So I decided to read their documentation ...
3
votes
2answers
258 views
Using automated bdd-gui-tests to keep user-documentation-screenshots up do date?
Are there developpers out there, who (ab)use the CaptureScreenshot() function
of their automated gui-tests to also create uptodate-screenshots for the userdocumentation?
Background: Whithin the ...
5
votes
3answers
923 views
How to document business rules
I am wondering what would be the formal and the most commonly practiced method of documenting business rules? Also how do you document the UI specifications of development artifacts (e.g. Documenting ...
1
vote
1answer
160 views
Metrics: Comments vs Documented API
I've been asked to run some code metrics in order to assess the quality of the code. One of the metrics was vaguely specified as "comments".
I ran Sonar on my code, and while I got 10% on the ...
14
votes
5answers
1k views
How are minimum system requirements determined?
We've all seen countless examples of software that ships with "minimum system requirements" like the following:
Windows XP/Vista/7
1GB RAM
200 MB Storage
How are these generally determined? ...
2
votes
2answers
236 views
Taking part in an open source project
I am new to open source development. I want to add some functionality to an open source project PRISM. But I couldn't find any developer guide or code architecture guide sort of a thing for it. How ...
2
votes
5answers
293 views
Run On Sentences in Technical Writing
This is just a question to think about.
When you write technical documentation and programming comments, do you ever find yourself writing run-on sentences in order to be more precise?
Is packing ...
5
votes
7answers
574 views
Is it wrong not to create Javadoc for my code?
I do a lot of Java programming at my work (I'm an intern) and I was wondering if it is generally a rule to create javadoc to accompany my code. I usually document every method and class anyways, but I ...
5
votes
1answer
259 views
How do you define a project for a web developer?
I am primarily a web designer, and a very rookie web developer.
Say I have a comprehensive web app I want developed through a freelancer on Odesk.com
What is the best way to effectively communicate ...
1
vote
2answers
134 views
How to use the APIs for different platforms?
From what I know, learning a programming language consists of :
1- Learning the syntax
2- Learning how does the language handle\use\implement its "abilities" (Classes, delegates, structs, ...
1
vote
4answers
214 views
Use the terms “vector” or “array” in high level discussion of C++ code
When I write high-level documentation about what an algorithm does, I use the term "array" to refer to the data structure on which the algorithm operates even though the actual data structure is an ...
7
votes
5answers
1k views
Why bother differentiating between functional and nonfunctional requirements?
I understand the difference between the two, but I get questioned by my colleagues of the benefit of labeling requirements as functional or nonfunctional (or transitional). Why bother to do so? He ...
12
votes
5answers
868 views
Do you create a design with UML before you start? [duplicate]
Possible Duplicate:
How often do you use Formal UML?
I'm currently following a study UML called UML Fundamentals.
While studying, I wondered if companies even bother creating system ...
6
votes
5answers
423 views
Learning about the Facebook Platform [closed]
I'm looking to learn more about the Facebook platform but I can't say I've found the IRC channel, the Facebook Developer Forum, or the online documentation very helpful.
Has anyone else recently been ...
34
votes
6answers
1k views
What should I do to leave a job professionally?
Given that the current employer knows and has been given appropriate notice ahead of time, how can a programmer make a clean job transition from his old job? What things should the programer consider? ...
10
votes
5answers
247 views
Code documentation: Public vs. Non-Public?
I'm one of those developers that has the mindset that the code written should be self-explanatory and read like a book.
HOWEVER, when developing library code for other people to use I try to put as ...
7
votes
5answers
285 views
What is the standard for modeling modern applications prior to development?
I'm taking on my first enterprise-level application and I want my team to model the entire ASP.NET MVC C# application before we even tap out one line of code.
UPDATE: This was not intended to be a ...
54
votes
17answers
9k views
What program do you use to write technical documentation?
I'm writing an architecture/technical documentation for an inhouse project and I'm becoming more and more frustrated with Microsoft Word as I seem to use most of my time getting things to align ...
3
votes
7answers
712 views
Writing better timesheet [closed]
Recently, my company started to require us to fill out a monthly timesheet, writing down everything you do in office.
A timesheet contain 29-31 days, depends on the number of days of the month. I ...
11
votes
2answers
271 views
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 ...
12
votes
6answers
445 views
Is saying “JSON Object” redundant?
If JSON stands for JavaScript Object Notation, then when you say JSON object, aren't you really saying "JavaScript Object Notation Object"?
Would saying "JSON string" be more correct?
Or would it be ...
7
votes
6answers
854 views
Is it necessary to write a javadoc comment for EVERY parameter in a method's signature?
One of the devs on my team believes that it is necessary to write a javadoc comment for EVERY parameter in a method's signature. I do not think this is necessary, and in fact I think it can even be ...
11
votes
7answers
563 views
Does it make me a bad programmer if I dislike the Agile methodology? [closed]
I like the small iterations. I like the unit tests. I like code review. What I don't like is the starting off with little or no documentation. Am I alone in this? Do I simply have a ...
2
votes
1answer
220 views
what info do wcf/.net developers need when joining a new project?
I'm a technical writer tasked to document a rather complex WPF/WCF .net application for a governmental agency. I'm not sure where to start and would like some suggestions from .net developers about ...
3
votes
2answers
340 views
H.264 documentation and ressources
I'm tasked to use an API on a small embedded linux device. The use of the API is rather simple, but there are a gazillion of (face it, not documented) parameters to control multiple aspects of the ...
