Want to protect your cyber security and still get fast solutions? Ask a secure question today.Go Premium

x
?
Solved

Best practices for helpful documentation?

Posted on 2014-04-22
9
Medium Priority
?
350 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
  • 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 400 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
What does it mean to be "Always On"?

Is your cloud always on? With an Always On cloud you won't have to worry about downtime for maintenance or software application code updates, ensuring that your bottom line isn't affected.

 
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 800 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 800 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

[Webinar] Database Backup and Recovery

Does your company store data on premises, off site, in the cloud, or a combination of these? If you answered “yes”, you need a data backup recovery plan that fits each and every platform. Watch now as as Percona teaches us how to build agile data backup recovery plan.

Question has a verified solution.

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

No other job is as rewarding and demanding as building an iPhone app is. It is not really in the hands of the developer for the success of an iPhone app. Many factors operate jointly for every iOS application's success in the market.
How do you create a user-centered user experience on your website? And what are some things you should consider in the process?
Learn how to create flexible layouts using relative units in CSS.  New relative units added in CSS3 include vw(viewports width), vh(viewports height), vmin(minimum of viewports height and width), and vmax (maximum of viewports height and width).
Starting up a Project

564 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