DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports
Events Video Library
Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
View Events Video Library
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

Mobile Database Essentials: Assess data needs, storage requirements, and more when leveraging databases for cloud and edge applications.

Monitoring and Observability for LLMs: Datadog and Google Cloud discuss how to achieve optimal AI model performance.

Automated Testing: The latest on architecture, TDD, and the benefits of AI and low-code tools.

Related

  • Low-Code Approach to Application Development
  • What Is a Modern Developer?
  • Atomic Habits and Software Engineering: Unlocking Career Success
  • Unlocking Game Development: A Review of ‘Learning C# By Developing Games With Unity'

Trending

  • What Is GitOps?
  • Researcher Finds GitHub Admin Credentials of Car Company Thanks to Misconfiguration
  • Introduction to ML Engineering and LLMOps With OpenAI and LangChain
  • NULL in Oracle

10 Software Documentation Best Practices

Cagdas Basaraner user avatar by
Cagdas Basaraner
·
Nov. 09, 12 · Interview
Like (4)
Save
Tweet
Share
42.57K Views

Join the DZone community and get the full member experience.

Join For Free
  1. Perform 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.
  2. Code 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.
  3. For 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.
  4. Requirements/issues/backlog 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 text file.
  5. Test 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.
  6. Documentation 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 worthless.
  7. For 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.
  8. Having 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 for documents.
  9. Document 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.
  10. Saving "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.
Software documentation code style

Published at DZone with permission of Cagdas Basaraner, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

Related

  • Low-Code Approach to Application Development
  • What Is a Modern Developer?
  • Atomic Habits and Software Engineering: Unlocking Career Success
  • Unlocking Game Development: A Review of ‘Learning C# By Developing Games With Unity'

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • support@dzone.com

Let's be friends: