1

I just started our bachelor thesis, and want to ask you how to make a proper documentation.

There are two pieces of software in our project's scope: a microcontroller software (node), and a server software (control_room).

We wish to place all project documents in the software repository. This way all information can be found in one place, and development-process choices can be linked with specific code.

Currently, it looks like: 

Folder                 Comment
----------------       -------------------
control_room/          source code for the server software
node/                  source code for the microcontroller software
docs/                  PROJECT DOCUMENTS (core topic of this question) 
README.md              small overview for the new readers

The docs/ folder for the project documents aims to set a clear picture on how the software was made. It has the following structure:

Sub-folder             Comment
----------------       -------------------
process/               All choices made during the project are reasoned here.
sprint_retrospectives/ Reflections on work done every 2 weeks.
supervisor_meetings/   Supervisor meeting minutes

Is this sufficient? How should we further develop it to meet our objectives?

Improve this question
3
  • Make it searchable! Commented Feb 3, 2020 at 22:20
  • Please elaborate @ThorbjørnRavnAndersen Commented Feb 4, 2020 at 11:15
  • What you are asking is essentially what file names you should use for future files. Wikis demonstrate that this is a problem separately from what documentation you should write, and that it can be made irrelevant. What is important, however, is the ability to search for phrases etc, which for most IDE's mean that your documentation should be in textual form and not e.g. word documents. Commented Feb 4, 2020 at 11:42

2 Answers 2

Reset to default
2

Documentation structure has both objective and subjective aspects. The subjective part is out of scope here. Furthermore documentation depend very much on the methodology. I will therefore propose you a list of general issues you need to consider in all objectivity, rather than a comprehensive answer:

  • Requirements: choices documentes in /process will probably be about your product and design choices. But how does your product fulfills its purpose ? And what is this purpose ?

    • Goals and requirements will inevitably appear in the meetings with your supervisors. Some others, you will discover within the team. But this is not sufficient. What about requirements that you discover together with users ? or legal requirements (e.g. GDPR if your nodes might record personal data, which would require privacy by design).
    • Since you're mentioning sprints, maybe most of your requirements will be user-stories or use-case 2.0 slices. If you make an industrial product, it would make sense to keep a track of all these even at the end of the project.

  • Integration: Whevever there are several components in a system, such as here node and control_room, there's always a third less visible endeavour, which is the integration between the components:

    • Where will you describe how both components are supposed to fit together ?
    • Where will you put your tests ? I could imagine that you'll have some unit tests in the structure of each component; but where would you have the integration tests that ensure that both components really work well together ?

  • Tests and quality: tests prove that your product works and meets the requirements. If you're in a traditional project, the acceptance process will require tests. If you're in an agile approach, every user-story will tell you about some success criteria that you need to cover with some kind of tests. If you're in TDD, well then you already know about the importance of tests.

  • Operator/user's manual: there are plenty of nice projects out there, that are useless unless you dive into the source code and a long history of design decisions. Think of those who'll have to make it run when you're not there. A minimum explanations about what to install where and how to run it seems required.

In addition, have you thought about maintaining a list of open issues? I.e. the kind of problems, questions or thoughts you'll have when working on the problem that you need either to answer asap, or tackle later? It's not mandatory, but personnally, it helped me and my teams a lot not to loose sight of problems which could hit us later.

Improve this answer
2
  • A minor point, but please consider that user stories, due to their frequent-changing nature, make horrible forms of documentation. They do show what was done in a snapshot of the moment, and therefor are nice for capturing decision-making details, but usually do not accurately describe the end-workings of software. Commented Feb 3, 2020 at 6:25
  • @Daniel Indeed. Personally I prefer use-case slices, which are very similar in practice, but help to shape a use case that will stay in the end. With user story mapping you can come to a very similar result, with a well identified backbone. But this being said, I’d prefer a succession of user stories « snapshots » that allow to retrace the evolution of the product (like 25 images can make 1 second of a cartoon) than loosing this information and having to guess why the product is as it is and what really matters to the user ;-) Commented Feb 3, 2020 at 8:18
2

Christophe above has provided most of the additional structure you need IMHO. I find that reviewing Github projects helps providing generic folder structures that people are accustomed to. From my various Confluence templates in addition to the above:

Folder (Comment)

Dev (folders for development) – this is what you / Christophe have described so far except for Operators / User manual – e.g. Ops below

  • Architecture (- architectural – non functional requirement, if not self evident)
  • Name standards
  • From Bitbucket/GitHub to production, per programming framework/Language
  • Central build server for builds for Server/Controller (- if any)

Ops (folders for operations)

  • Provision server-platform (- any ops tools / sw you use should have each own folder)
  • Installation of CI/CD pipeline (- if any)
  • Generations/versions of Server/Controller in production
  • Security (by design and in production) (- e.g. certificates, tokens, encryption, passwords)
  • Operations management
  • Troubleshooting
  • Logging
  • Monitoring
  • Performance
  • Remote management

How-to articles

Dictionary

Improve this answer

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.