What’s the best approach for multi-layered project documentation?
Asked by
CuriousCoder42
I'm starting a new team and have a lot of freedom in how I want to set things up. We're primarily developing Windows Forms using C# and Visual Basic, with a SQL Server database. We also plan to implement custom reporting and automated testing (possibly with some AI features for formatting flags) while using Gitea for version control. I'm aiming for a comprehensive three-tiered documentation setup, which includes: 1. A user manual for end users. 2. An installation guide with requirements for partner IT departments. 3. Detailed code and database documentation aimed at the development team. I'm curious about the methods and tools others have used successfully in similar situations. Any thoughts?
Answers
I generally think about documentation in terms of who it's for and whether it's permanent or temporary. For instance, user stories might be less valuable once the discussion is over, while API docs should be stable. It helps clarify what needs to be prioritized.
Reply to this answer
I really like separating documentation by audience instead of trying to put everything in one place. For user manuals, I’ve had great success using tools like Flipsnack to create browsable guides. It makes the info feel more accessible. Markdown works fine for the dev stuff, and platforms like Confluence or Notion are great for IT documentation.
Reply to this answer
A layered documentation strategy like yours is smart. Remember to keep user manuals simple and focused on tasks. IT documentation should be practical and straightforward, similar to a runbook. Dev and database docs should closely reflect the actual code and database schema so they remain relevant and useful.
Reply to this answer
Confluence is a solid choice for knowledge sharing with less technical audiences. For developers, sticking to good old markdown documentation in Gitea usually does the trick without any fuss.
Reply to this answer
One piece of advice I've found helpful is to write the user manual first. It might sound tedious, but it forces you to see things from the user’s perspective instead of just listing features.
Reply to this answer
Add your answer
Answers are reviewed before publication.
Related Discussions