Perhaps that way naturally aligns with the way our stuff gets installed - the installation team is only really interested in the places they can connect wires, the monitoring and control team wants to know how to use the interface, and so on.
There are two main styles of technical documentation writing, task focused and feature focused. The structure of documentation heavily depends on why you're writing the documentation in the first place, it sounds like your docs are aimed at specific groups that have specific tasks they need to perform based on it. Documentation for something like Raspberry Pi by necessity can't be that, it has to be a mix of task and feature focused materials, and the balance between the two — and how that is structured — is hard to do well. We try, and sometimes we succeed and sometimes we fail.
The online documentation for the Raspberry Pi still has a lot of legacy structure from before it was taken in-house, as a result the structure (and organisation) isn't well done in places. I'm hoping that over the next year or so, as other priorities get out of the way, we can start addressing that.
Statistics: Posted by aallan — Tue Mar 12, 2024 3:14 pm
