LX Group discusses the importance of Project Documentation

No matter the size of your next project, from the creation of a simple tool to the most complex embedded hardware designs – documentation is a key requirement at all stages of development. It allows for a constant reference to the project details during development, offers an articulate form of progress during project development to the stakeholders, helps with project hand-overs, and once completed provides a useful reference for all stages of the project and of course the end user or client.

Various organisations may use different project management styles – however the requirement for documentation encompasses all stages of the project. And the definition of documentation can vary at different stages of the project, for example some may consider documentation to just be end-used instructions; whereas it can encompass many forms. Using the “waterfall” method of project management as an example, we will consider documentation requirements for each stage of the project.

Before moving forward with the project, the forms of documentation required should also be considered. During the processes there will be a constant stream of internal notes, designs and other forms of record that need to be indexed and filed for later reference and modification. This is the ideal time to formalise the record-keeping structure of documentation and decide on the medium of record.

In the requirements specification stage, it is important to invest time into not only determining the requirements and goals of the project, but to ensure that every point of interest, detailed specification and requirement is recorded and made available to the project team. The customer must be made aware that this is the key stage in setting the project goals and requirements, as any changes further on will alter the final cost and completion timeline.

The design stage of the project will involve conversion of the requirements into a formalised foundation that gives engineers a starting point with which to develop the product or service. All team members working on the project must not only refer to the customers' requirements and keep them at the forefront, but also make detailed notes and document their work at all times. This not only includes the usual tasks such as documenting software, or creating circuit schematics – but also notes written after designing, explaining how things work in their own language.

Although some may find this tedious and a distraction from “real work”, by not doing so they will automatically create time-consuming problems for themselves when required to revisit existing work in the future. Furthermore (if required) when the time comes to write end-user documentation, the author can refer to the engineers' notes on how the product or service works which helps minimise the time taken at that stage.

During the implementation stage of the project, the need to refer to documentation created in earlier stages will be crucial for the implementation team. They may have been introduced to the project after the starting point, and need to familiarise themselves quickly. Furthermore during implementation the documentation will need to be updated to allow for the addition of end-user instructions, possible variances to the original specifications, and unexpected possibilities made available by project features. Through the implementation process, existing documentation can also be updated with the goal of creating the start of external documentation for the end user and client.

Once the project verification stage has commenced, the quality and detail of internal documentation will be one of the major factors in the success of the process. As staff move in and out of the project – knowledge can be lost or opposing viewpoints and experience introduced due to the personality of different people. Only by having everything documented will you have concrete information with regards to “how things should be”.

Furthermore at this point the need for end-user documentation will need to be finalised. By referring to the design documentation and notes, an accurate representation can be viewed by the author allowing them to create overviews, instructions, tutorials, sales material and other output for the public face of the project. At this stage the output for external use should also be reviewed by an independent editor – someone not involved in the day-to-day workings of the project, but whose speciality is documentation itself.

Although it may be simpler to print and index everything as it is created, the use of a secure internal “wiki” - or online website that allows users to add and update content may also be considered. As well as providing revision tracking and recording of all versions of information created, they can provide a fast method of information retrieval and speed up the final documentation process. However the success or failure of using internal online methods will rely on the strength of the organisations IT security policies and the proficiency of the team creating it.

It is the task of an editor to not only check the documentation for spelling, grammar, and form it into the required layout – they must also ensure the documentation “makes sense” and is approachable for the target user. As part of this process the editor can also liaise with the client and include them in this process in order to mould and create documentation in all forms that satisfied their requirements.

Although this is only a small precis of the full requirements of documentation in any project, we hope this highlights the importance of quality documentation in your projects.

And in saying that, LX recognises the importance of accurate and thorough documentation. The depth and form of documentation can vary depending on the requirements of the client and project. LX can develop documentation including:

• Software and firmware documentation including commented source code and flow charts to professional and industry standards
• Design documentation including using abstraction tools to produce traceable design decisions
• User, installation and maintenance documentation
• IP documentation to develop and secure intellectual property
• Due diligence and functional safety documentation
• Certification and testing reports

The team at LX has developed a number of systems in this area and has extensive experience with the core technology requirements of such systems. We understand the importance of high availability, accuracy and integrity of the systems, combined with the need for future proofing infrastructure rollouts.

For more information or a confidential discussion about your ideas and how we can help bring them to life – click here to contact us, or telephone 1800 810 124.

LX is an award-winning electronics design company based in Sydney, Australia. LX services include full turnkey design, electronics, hardware, software and firmware design. LX specialises in embedded systems and wireless technologies design. www.lx-group.com.au

Published by LX Pty Ltd for itself and the LX Group of companies, including LX Design House, LX Solutions and LX Consulting, LX Innovations.