Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

In science, intellectual contribution to a project is sufficient for someone to be the author of a document. When writing software documentation, this would imply that almost everyone involved in the software development would be included as co-authors.

Unlike in science, it seems odd to include the names of people who do not actually work on the document. One reason is that documentation is constantly evolving and I am concerned about making sure that co-authors regularly review the current state of the document.

question: When writing documentation, are there guidelines for whom, other than those who directly contribute to the document, should be considered an author?

clarification: I am writing documentation about how to use an open source software and database built by and for scientists. As this project represents most of our the team's cumulative experience with software development, we have no existing policies for authorship of documentation (unlike we do with journal articles).

share|improve this question
add comment

3 Answers 3

I'm not sure what type of documentation you are creating or attempting to keep current, but in my 20-odd years of technical writing I have never had my name on a single document that was exposed to the public. One reason is that I am a contractor, and most companies are loathe to admit they use us as much as they do.

If it is the policy of to include authors, I suggest you list them by role: authors, contributors (someone who wrote less than a chapter/section), reviewers, editors, illustrators, and perhaps even those who inspire(d) you if you feel the need.

share|improve this answer
    
it had not occurred to me not to include authors, although this seems reasonable. –  David Aug 30 '11 at 21:37
add comment

In my experience, the author or authors are the people who actually contribute core content to the document and produce the work. Other people who might sign-off on the document are listed as "reviewers". Typically, there will be two pieces of information associated with every name - their role in producing the document (as an author/contributor/originator or a reviewer) and their role in the organization (software engineer, project manager, software lead, quality assurance, and so on).

However, this depends on organizational policies. Your team or organization should decide who writes what types of documents, who has to review, how those reviews are documented, and how to capture any kind of required sign-off. This should be captured as part of your configuration management procedures - documents need to be controlled just as much as source code does.

share|improve this answer
add comment

Depending on what sort of documentation it is, NO authors should be named or the company / organization publishing the document is listed as the author.

For example,

Be warned: all above links are to PDFs, some of which are quite large.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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