How do you track changes and revisions in your documentation?

Some other popular version control systems to consider are: -Sphinx -Docusaurus -Monotone However, using a CMS may be a more straightforward approach for some organizations. CMS platforms may include versioning features and can be suitable for teams that focus on content creation rather than code-based documentation.

Forget document disasters! Version control is your magic wand, letting you rewind edits, collaborate seamlessly, and ditch versioning mayhem. With one central hub accessible from any device, it's like instant documentation harmony. Git, Subversion, or Mercurial – pick your tool and watch your doc-life transform!

Ensure that all parties associated with the document are updated to your changes. If they do not update their computer software, you can easily be brought to a meeting with an angry manager. This happened to me once, I then realised it was time to move on.

Yes, agreed - file naming convention is a simple yet robust way for document version control - but requires consistent discipline.

Naming conventions are central to version control. Without naming conventions in folder hierarchies the difficulty in searching for specific documentation alone, not even including version control archives, increases rapidly with a growing document library. Even software services with search functions become nearly unusable when there isn’t a fixed naming convention. Without knowing what the title of a document is, all one can do is guess at possible titles and hope you get lucky. This can lead to writing another copy of a document that already exists if you can’t track it down in an online software service with thousands of saved documents.

Naming conventions are necessary for every technical content library no matter where each is hosted. But relying on naming conventions to track document versions is an archaic practice replaced by documentation software like Confluence and SharePoint, and full VCS tools, for very good reason. Using naming conventions to track versions leads to chaotic indecision and an indecipherable mess. Too often, organizations do not consider that documentation is as much of a data asset as coded data is and then they shoot themselves in the foot when they choose not to invest in modern documentation management tools.

Yes, an excellent idea! Sometimes, people go on holiday and the updates to their documentation have to be done by someone else. If that person cannot identify the latest document by the person on holiday, it generates enormous anger. When working in the defence industry, I once actually witnessed a senior author, cry out about a person, and sling a chair across a room!

The good news is that most people understand the need for a naming convention. However, they are challenging to maintain when you are working with multiple stakeholders, external vendors, or when employees come and go. Documentation is key here. Note business specific nuances such as: accrediting bodies, major divisions, series, etc. Consult with a few team members outside your immediate area to get their input and to avoid proximity blindness. Finally, a strong naming convention can be critical for reporting. Think through your reporting needs in advance (internal and external) so you can build a robust naming convention that reflects the business needs and priorities.

"In the world of version control, a commit message wields great significance as a concise account of file changes. Collaborators find value in understanding the history and purpose of revisions. To craft an effective commit message, adhere to a standard format comprising the type of change (e.g., edit, add, delete), scope of change (e.g., section, paragraph, sentence), and the reason for change (e.g., fix, update, improve). For instance, a commit message may read like this: 'edit: introduction section - update product features.' This practice ensures clarity and facilitates seamless collaboration among the team, fostering efficient version management." In the end. To be clear is to be kind!

Commit message is a key meta data that provides additional content for any commit. It helps audit and review changes later in the project stage. It also makes it easier to identify, modify, change, delete or revert a commit in the future. Task/ticket ID in the commit message also helps to trace a commit back to an origin doc issue. Commit message is most important in situations where you need to cherry pick commits from one branch to another branch to customize a version of your doc and have a distinct branch to work and build on.

It is a great idea to integrate Git and Jira. Then, adding a Jira ticket ID to the commit message will also create a link to the commit from the ticket. In this way, a Jira task would contain a link to the specific commit/branch/pull request containing the changes. This adds to transparency and makes it easy to understand what exactly changed in the docs for a particular task.

Writing clear and concise commit messages helps other team members as well as community understand the purpose of changes you made. The standard commit message follows 50, 72 rules. 50 characters for the title of the commit. 72 characters per line for the description in the commit message.

I recognize the importance of clear and concise commit messages. I convey the purpose and scope of changes succinctly, using descriptive language. Each message follows a consistent format, highlighting what was modified and why. This practice aids collaboration and facilitates understanding across team members. By writing clear commit messages, I ensure transparency and accountability in documentation revisions, fostering efficiency and maintaining clarity throughout the development process.

Comments and annotations are a great tools for collaboratove writing, reviewing etc of documents. They can also be the backbone for your changelog - annotating the document changes as ypu make them, allows ypu to easily summarize them into a changelog later.

It's crucial to schedule regular meetings with reviewers when utilizing comments and annotations in the document review process. In my experience, without a structured approach, groups can lose track, leading to a document overloaded with comments and numerous unresolved questions. To mitigate this, it's essential to address comments to specific individuals, fostering accountability and ensuring that questions are promptly addressed. Effective communication and periodic meetings are key to a more streamlined and productive review process.

SMEs should review documents using a platform that supports a robust commenting system. Microsoft Word is excellent because of Track Changes, and comments with tracking and tagging. The easier it is for the SME to make clear comments, the better quality documentation review you receive. Most HATTs (Help Authoring Tools), include poor - mediocre review tools. Which focus on the writer and not on the reviewer. I prefer to take the extra time to create a reviewable doc that is the easiest to review

Yes, in normal situations this is the perfect system! However, I recall a manager once requested that I update a document (not originating from me), for another manager flying from the UK to USA that evening. I finished the task in the early hours around 2:00 a.m. I then sent the document by email to this manager during his flight. This is sometimes the real-world!

Maintain a Change Log: Keep a detailed log within your documentation that records each change, including what was changed, why, when, and by whom. This is especially useful for keeping track of updates over long periods. Release Notes: Create release notes for significant updates, summarizing the most important changes for the end-users.

For groups using a Jira system, take advantage of the Comments field when revising the documentation related to a particular ticket. You may even have a Jira ticket dedicated to track documentation development tasks. Be sure to balance the scope of granularity you are tracking in the ticket. What often works well is a single ticket for each sprint. As you complete a task, move the ticket across your workflow's status groups: To Do, In Progress (which can have subtasks like Research, Draft, Formatting), In Review, Approved, Done. The changelog will be part of the ticket metadata. The ticket can be closed at sprint's end or pushed to the next sprint. If possible, link your documentation tickets to other project boards from dev or proj mgmt.

You should always have change management logs in major/ long documents. At least to record details prior to publication. Once published this information may be less relevant for certain types of document. The change logs should record details on: - The Master document reference details, e.g. Document title, author, date and version of last edit, etc. - The changes made in the last edit. - The reviewers/ proof readers of the documentation, prior to publication.

Keep a separate document or section within your documentation for a change log. Record details such as the date of change, the person making the change, a brief description of the modification, and the version number.

Yes, it's always best to get a peer review, as sometimes the documentation is so close to you, that points can be missed. I've reviewed the work for many authors in my time. Once, I received several chapters of a novel to review. The chapters were past to me from an old friend. He was very grateful as I found a flaw in the plot that went unnoticed. Another method of testing, is to get a text reader to playback what you have written. I know of other authors who use this method. I've also used this method on my own work many times since I've retired!

Peer review plays a pivotal role in guaranteeing the precision and consistency of documents. Even after dedicating substantial time to a document, it's easy to become "blind" to errors and oversights. Additionally, I rely on "PerfectIt" for a comprehensive final check of my work. PerfectIt is a proofreading software that checks documents for consistency and errors in formatting, style, and terminology, helping to ensure document quality and adherence to a specified style guide. For intricate documents like clinical evaluation reports, a reference manager is indispensable.

With a VCS, it’s easy to get peer reviews, particularly for changes to existing documentation. Set up the VCS to send out diffs of changes, e.g. by email, to the whole team of writers, or even to a wider group that would include PMs or engineers. Since those diffs will often be small chunks of changes, the likelihood of getting peer reviews is higher than with a CM/S simply because the review process is unobtrusive for reviewers: look at a short email, reply to the author, done. By comparison, reviews of changes in a CM/S or wiki are more cumbersome because they involve more steps, and thus require more of a reviewer’s time.

Reviewing documentation involves more than just verifying its accuracy; it also contributes to skill enhancement, sharing expertise, and fostering team feedback. By establishing this process, you'll achieve the following benefits: - Enhanced accuracy and completeness through double-checking (resulting in a lower percentage of mistakes and bugs); - Receipt of feedback from the team or supervisor (helping you identify areas for improvement and personal growth); - Tool for distributing knowledge and expertise within the team

I find reviewing your documentation method with case scenarios to be the most valuable method of evaluating your process for improvement. Many times, we find ourselves in a cycle of great thoughts and opinions, but data provides the best navigation. Put all the pieces in place, from clear comments, version-controls, etc. and build true value in a retrospective to weigh what worked and what requires improvement.

In aerospace technical documentation, a revision bar is often used to indicate significant changes, additions, or new sections in a document. This visual indicator helps readers quickly identify the areas of the document that have been updated or revised. When readers see a revision bar, they know that specific information has changed or been added, which is crucial in an industry where precision and accuracy are paramount. The use of revision bars in aerospace documents, along with clear version control and documentation standards, helps maintain the integrity of technical information and ensures that readers can easily recognize the most recent and relevant content.

If the documentation is important to you (it could be your future with the firm), make a copy for yourself. I once sent a document to personnel, with proof of my actions, and it had been checked by two managers. However, despite being assured several times by personnel that they would attach the report to my annual report, it was lost. On leaving the firm, in the Exit Meeting, the personnel had no answer to why they lost my report!

Trace the digital print of the document from its details. Look who, when, and where the document is created. In that way, document can be traced with certainty.

It’s almost 2024 so for gods sake subscribe to a cloud based EQMS. MS Office and many other disjointed tools had their time. With trusted and true SaaS EQMS solutions any business whether a startup or large enterprise can very quickly and easily implement a robust QMS. Document management is one of the key elements of that.

What about using a ticketing system such as Jira to track the background info of each change request and requirements? A ticketing system such as Jira and a version control system such as Git plus an integrated review toolchain will better serve the end to end tech doc workflow.