Published at DZone with permission of Cagdas Basaraner, author and DZone MVB. (source)
documentation as required (e.g. %10 of total production time). No
documentation is never a good solution as much as excessive
documentation. It may include code documentation, requirement
specifications, design documents, test documents, user manuals etc.
Those documents are needed to be managed and shared also, by using
version controlling tools and/or web based platforms.
documentation is important. Best way of doing this is producing
self-documenting code. Variable, method, class, package etc. names must
be meaningful and codeflow must be pure. For very complex code sections,
short comment lines may be included. Javadoc-like standard entries are
not required but may be added for auto document generation from code.
the future developers, short and useful design documents may be
prepared including key design features and UML diagrams. Practical user
help documents may be useful also. These documents must not include
unnecessary bulk info.
item/function points tracking is important. For that operation, a
tracking tool is more effective (it will have quick search, edit
capabilities and a few more features) than writing them into a plain
tracking is also important. Test scenarios and results may be tracked
using tools (or with text files, which is not preferred) and associated
with related requirements. By doing this, functional status of software
may be monitored easily.
is a live process. If you produce some documents, it is a good practice
to update or produce new version of those documents until the end of
development process. If a document is not up-to-date, it is practically
text file documents, versioning is important. For each new version of a
document, a new version number (which is given with a stable versioning
strategy) must be given. Also a version tracking table having change
info may be included for better tracking.
a consistent document template is important for companies. Header,
footer, headings, font sizes must be consistent in document and among
other documents for better readability. It is also a good practice that
having a cover page, table of content, table of pictures and a glossary
formatting, language usage and typing are other physical issues about
documents and attention must be paid. Typing errors, unconsistent table
sizes, indentations etc. will distract the reader.
"lessons-learned" info on a shared place is another good practice.
Those items are some useful experiences (information or
code/configuration sections etc.) about development process which may
not be included in standard process documents. Lessons-learned info may
give acceleration to the current developers or future developers about
some challenging and repeating operations.
(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)