Solved

Best practices for helpful documentation?

Posted on 2014-04-22
9
341 Views
Last Modified: 2014-04-25
Hello everyone,

Part of my job is to create specifications and wireframes for projects that our engineers and web producers develop. An important aspect of specifying a project or feature is creating documentation for it.

I'm wondering if any of you have any recommendations for writing documentation that is helpful to the people who read it (said engineers and web producers)?

I'd love to hear from both people who write documentation and people who use/read it.

Thanks!

mollymew
0
Comment
Question by:mollymew
[X]
Welcome to Experts Exchange

Add your voice to the tech community where 5M+ people just like you are talking about what matters.

  • Help others & share knowledge
  • Earn cash & points
  • Learn & ask questions
  • 3
  • 3
  • 2
  • +1
9 Comments
 
LVL 18

Expert Comment

by:Jerry Miller
ID: 40015653
When you are writing documentation, you should take into account the audience and purpose of the doc. A glossary is always helpful as it explains the terms used throughout the file regardless of the document type.

As a developer I like to see a business requirements document that has been approved by the user base management. This should detail what they need the application to do in order to be usable for them. I also like to see current functionality that is in use and well as a to-be functional process document. The To-be one is what I use to start creating the program itself.  

Using the To-Be doc, I create mock-ups of the pages and show them to the involved parties to get their buy-in. After they have approved the mock-ups, I create the code behind them and make them functional.
0
 

Author Comment

by:mollymew
ID: 40017848
Hi jmiller1979,

Thanks for the reply.

Since you refer to that "To-Be" doc when you're developing an application, I'm wondering -- what level of detail in that document is most helpful to you? Are you able to ask questions of the person who wrote or approved that document? Are you more likely to refer to the document or to the person?

I'm the person who will document the requirements and then give them to someone else to develop. I often write things out in detail but I still get a lot of questions verbally that are answered in my documentation. I often wonder if this is just a preferred method of communication, or if my documentation is hard to digest.

mollymew
0
 
LVL 10

Assisted Solution

by:acbxyz
acbxyz earned 100 total points
ID: 40017884
> I often wonder if this is just a preferred method of communication, or if my documentation is hard to digest.

The only one who can answer this might be the one with the verbal questions.


It is hard do explain how detailed a documentation should be. It also depends on the project complexity.

Try to explain what you want as result, not a possible way the programmer could go.
A draft/drawing could be helpful, too.
0
Revamp Your Training Process

Drastically shorten your training time with WalkMe's advanced online training solution that Guides your trainees to action.

 
LVL 33

Expert Comment

by:Paul Sauvé
ID: 40018537
There are different documentation requirements:

Software Development Life Cycle phases
There are following six phases in every Software development life cycle model:
   1.Requirement gathering and analysis
   2.Design
   3.Implementation or coding
   4.Testing
   5.Deployment
   6.Maintenance
Each phase has corresponding documentation. For example, the Deployment phase documentation is usually the User Guide
0
 

Author Comment

by:mollymew
ID: 40018594
Thanks, everyone.

Do you guys ever work from documentation? Are there any characteristics of good documentation that's easy for you to read and understand?

mollymew
0
 
LVL 18

Expert Comment

by:Jerry Miller
ID: 40018660
The current functional documents for our projects are essentially the user guides. The To-Be docs are an outline of what is needed to happen. For example, if we need to upload an Excel file from another source so the new process will be to browse to the location of the file and click on upload.

We get into what buttons will be on the pages and their function. My business analyst works with the users and develops what functions are needed. Then I work with her and determine how best to implement the needs. We document all of this into the various docs and have the user base, project managers, and other interested parties sign off as we get them completed.

I develop my project plan from the functional document that me and the BA work out. Then I work from the project plan. Everyone does things a little different, so you should sit down with the developers and see how they like to do things. There may be some give and take depending upon how flexible each side is on these items.
0
 
LVL 33

Assisted Solution

by:Paul Sauvé
Paul Sauvé earned 200 total points
ID: 40018749
Functional documentation (or Business Model documentation) and Help documentation is used by both technical and non technical staff.

Functional documentation and data models are also the basis for the organic analysis, which is used by programmers.

Comments in the program code is also VERY useful for system maintenance and is quite often non existent.
0
 
LVL 18

Accepted Solution

by:
Jerry Miller earned 200 total points
ID: 40020217
Are there any characteristics of good documentation that's easy for you to read and understand?

It should be detailed enough so that someone picking up the document could understand it. That varies depending upon the complexity of the project. I have 100 page functional documents, but most of our projects are relatively small and it usually only 40-50 pages.
0
 

Author Closing Comment

by:mollymew
ID: 40022957
Thanks for your input, guys!

mollymew
0

Featured Post

Free Tool: IP Lookup

Get more info about an IP address or domain name, such as organization, abuse contacts and geolocation.

One of a set of tools we are providing to everyone as a way of saying thank you for being a part of the community.

Question has a verified solution.

If you are experiencing a similar issue, please ask a related question

When it comes to write a Context Sensitive Help (an online help that is obtained from a specific point in state of software to provide help with that state) ,  first we need to make the file that contains all topics, which are given exclusive IDs. …
Q&A with Course Creator, Mark Lassoff, on the importance of HTML5 in the career of a modern-day developer.
The viewer will learn how to create and use a small PHP class to apply a watermark to an image. This video shows the viewer the setup for the PHP watermark as well as important coding language. Continue to Part 2 to learn the core code used in creat…
Starting up a Project

635 members asked questions and received personalized solutions in the past 7 days.

Join the community of 500,000 technology professionals and ask your questions.

Join & Ask a Question