Take the 2-minute tour ×
Writers Stack Exchange is a question and answer site for authors, editors, reviewers, professional writers, and aspiring writers. It's 100% free, no registration required.

I noted in this question:

What is the best way to learn technical writing?

...that a rated method to learn how to write technical documents is to imbibe good examples.

Can you recommend any examples of good code/ database documentation that have proven useful?

This was also a really useful thread in terms of documenting code: How can I write better code-based reference documentation for programming interfaces?

I am documenting a large number of programs so that developers can rewrite and maintain the code and database. The documentation will be directed at developers who will be maintaining and re-writing the code, rather than end-users. Any advice, dos/ don'ts, words to the wise much appreciated.

share|improve this question
    
Hi and welcome to Writers. I'm always happy to see more tech-writing questions here. As written this is pretty broad, though, and it seems like it will lead to an opinion survey more than good solid answers. Could you perhaps pick one aspect of this kind of writing and ask about that? Maybe you're trying to write tutorials, or docs for something that supports a lot of user customization (imagine trying to document Firefox in the face of add-ons and userscripts), etc? Are you asking about organization, use of examples, phrasing, user assessment, etc? Thanks. –  Monica Cellio Jul 18 at 23:41
    
Do I understand correctly that your documentation is directed at people modifying the code (and thus needing an understanding of its inner workings), rather than at people using the code (and thus only needing an understanding of the interfaces)? –  celtschk Jul 19 at 14:28
    
@celtschk Thanks for your comment. Yes, I should have specified that the documentation is directed at developers who will be maintaining and re-writing the code, rather than end-users. –  Stefan Piskorski Jul 21 at 8:22
    
Related question on SO: What do you consider good API documentation? although the answer contains more of negative examples. –  SF. Jul 21 at 10:10
    
@SF Thanks. There are some useful links in the answers. –  Stefan Piskorski Jul 21 at 13:02

2 Answers 2

up vote 9 down vote accepted

Introduction

The Biggest reason documentation is written is to help developers learn about the software system and give them a reference to the tools they are using. This is a broad question and I must admit most of the tips I will give will be my opinions and things I've found helpful. Below are some guidelines and design aspects you can use to help improve you documentation.

Know Your Audience

This may sound like a silly thing but it is very important. Knowing your audience helps you decide how much detail you need and what information you need to provide. For example, You don't want to present all this unnecessary low level details about your system, and techno jargon to someone who just wants to fix little bugs in your system or test your programs. You also want to accommodate for the advance developers you want to really change your system, they don't want to many abstractions and not enough detail about a system.

Django is an example that does a good job identifying their audience and accommodating for their different targets.


Make It Easy to Find Information

When developers get stuck on a problem or want a quick look at what arguments some function takes or what it does, they don't want to have to look through thousands of links just to find what they are looking for. Just like you might not want to read all of this answer if I didn't have headers. Creating an easy navigation system for your documentation makes it clearer. I would suggest a contents table or a searching function. Also creating a structure for you documentation help readers find what they are looking for better.

Android does a terrific job with this. Dividing their content into Design, Develop, and Distribute gives developers and idea of where to find the information they are looking for. Their search function makes finding information easier.


Spruce It Up

Give you audience a choice on how they want to receive the info. Not everyone wants to read long lines of text. Some people might want to watch videos, others might want to look at an infographic. Even if you you just want to use text then put your documentation in the form of a story, or make it more personal.

Qt does a good job providing different mediums of documentation. Ooc programming language does a good job sprucing up their tutorial by making it into a story.


Closing

Writing documentation is boring and difficult but it can be very helpful to your software. Just always remember who you are writing for and why you are writing. You can use any guidelines you want. Hope you found this helpful and I would welcome any criticism.

share|improve this answer
1  
Welcome to Writers! –  Neil Fein Aug 24 at 4:47

In test-driven development the emphasis is on writing tests that clarify what code should do, rather than extensive documentation. Future maintainers of the code can then ensure that the code continues to exhibit the behavior it should by virtue of the tests.

The way tests are named form a type of documentation of the proper behavior of the code. Here is an example from the Ruby world:

describe "REST interface" do
  describe "create" do
    context "with valid parameters"
      it "should create an object in the database" do
        # test logic goes here
      end
      it "should return HTTP 200" do
        # test logic goes here
      end
    end

    context "with invalid parameters" do
      it "should not change the DB" do
        # test logic here
      end
      it "should return HTTP 400" do
        # test logic here"
    end
  end
end

The block names are chained together, so that you can read them in English and they make sense: REST interface create with valid parameters should create an object in the database.

share|improve this answer

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.