Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »

Review Suggested Edit

You can't approve or reject suggested edits because you haven't yet earned the Edit Posts ability.

Approved.
This suggested edit was approved and applied to the post about 3 years ago by Monica Cellio‭.

7 / 255
  • # 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](https://docs.djangoproject.com/en/1.6/) 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](http://developer.android.com/index.html#) 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.
  • # 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 your 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 advanced developers you want to really change your system: they don't want too many abstractions and not enough detail about a system.
  • [Django](https://docs.djangoproject.com/en/1.6/) 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 your documentation help readers find what they are looking for better.
  • [Android](http://developer.android.com/index.html#) 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 your 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 just want to use text, 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.

Suggested over 3 years ago by msh210‭