1

We maintain a technical project whose specifications are in a document of few hundred pages. It's a text document (Word), not a Wiki or a Web-based stuff.

The document contains lots of tables with values (strings, numerical, parameter names) . Some tables are huge (hundreds of data), other are quite small.

I'm looking for good practices/best approaches to get readable and comfy documents, especially data tables, avoiding hard to distinguish rows from content around, and also not some overly colored stuff making it hard to focus on. (As a side note, the specification contains also pseudo-code and code samples, formatted and highlighted with styles in a way like does SE markdown engine.)

I got this article : Web Typography: Designing Tables to be Read, Not Looked At. It's aimed at Web design, It might be good for such documents.

Are there guidelines to write a easy-to-read technical specification? I understand it might be a subjective question... Some people likes colorful documents, others sober ones.

Improve this question
2
  • A vague question about "easy-to-read technical specification" in general is way-too-broad for the Q&A format for this site, and if you are asking for links or books: questions for 3rd party resources are off-topic here, please have a look into the help center. But to your specific question about tabular documents, I think the linked article in your question can be applied to your case immediately, I could not see anything at a first glance which restricts it to Web design.
    – Doc Brown
    Mar 6, 2020 at 11:46
  • @Doc Brown, thanks. The question is specific to tables. (By the way I may have exaggerated by saying "hundreds" of datas, I wasn't meaning hundreds of rows).
    – Amessihel
    Mar 8, 2020 at 19:43

1 Answer 1

Reset to default
2

Large, highly-detailed, fiddly stuff is usually relegated to Appendixes, linked to be a hyperlink (for the online crowd) and/or a Page number (for the hard-copyists) in the main document.

That way, the reader can have both "open" at the same time, regardless of their reading medium of choice.

Read up on the HyperLink and PageRef Field Codes in Word.

Improve this answer
2
  • Appendixes are a double-edged sword: they are fine to swap out things like statistics from the main part of a document, in case that main part can be understood without the appendix. But in case the "detailed stuff" is essential for the spec, they require the reader to switch back-and-forth between two different positions in the document (and yes, I read you idea of having "both" parts of the doc open at the same time). So I am missing here a clear warning in this answer to use appendixes with care, for not making the readability worse.
    – Doc Brown
    Mar 7, 2020 at 10:00
  • It's very hard to not turn a specification basically to a trashcan where you put stuff you won't read next, cause it stinks.
    – Amessihel
    Mar 8, 2020 at 19:44

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.