Solved

Best practices for helpful documentation?

Posted on 2014-04-22
9
308 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 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
 
LVL 31

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
Highfive Gives IT Their Time Back

Highfive is so simple that setting up every meeting room takes just minutes and every employee will be able to start or join a call from any room with ease. Never be called into a meeting just to get it started again. This is how video conferencing should work!

 

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 31

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

Highfive + Dolby Voice = No More Audio Complaints!

Poor audio quality is one of the top reasons people don’t use video conferencing. Get the crispest, clearest audio powered by Dolby Voice in every meeting. Highfive and Dolby Voice deliver the best video conferencing and audio experience for every meeting and every room.

Join & Write a Comment

Suggested Solutions

Title # Comments Views Activity
Form submit issue 11 54
Summernote and form validation 10 42
Fixed div within Bootstrap carousel item 11 28
Not needed 13 57
Entering a date in Microsoft Access can be tricky. A typo can cause month and day to be shuffled, entering the day only causes an error, as does entering, say, day 31 in June. This article shows how an inputmask supported by code can help the user a…
In this article, you will read about the trends across the human resources departments for the upcoming year. Some of them include improving employee experience, adopting new technologies, using HR software to its full extent, and integrating artifi…
Viewers will learn how to properly install Eclipse with the necessary JDK, and will take a look at an introductory Java program. Download Eclipse installation zip file: Extract files from zip file: Download and install JDK 8: Open Eclipse and …
The viewer will get a basic understanding of what section 508 compliance can entail, learn about skip navigation links, alt text, transcripts, and font size controls.

757 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

Need Help in Real-Time?

Connect with top rated Experts

21 Experts available now in Live!

Get 1:1 Help Now