Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Doc formatting #10

Open
dkfellows opened this issue Feb 19, 2024 · 0 comments
Open

Doc formatting #10

dkfellows opened this issue Feb 19, 2024 · 0 comments

Comments

@dkfellows
Copy link

I approve of you making the overall documentation files at the top of the project. That's very very good practice indeed! However...

I recommend making the parts of the documentation that are not exact technical phrases be set in a variable-width font. For example (in TechnicalManual.docx):

\src — contains all the source files, <*.h> libraries of the project and the main.cpp file. In particular, \src directory contains several subfolders with project libraries:

would be better as:

\src — contains all the source files, <*.h> libraries of the project and the main.cpp file. In particular, \src directory contains several subfolders with project libraries:

It makes the different parts "pop" correctly to the eye of the reader-in-a-hurry. The more complicated the document, the more important it is to get these sorts of things right. Particular attention needs to be paid to "technical phrases" (things you might cut-n-paste into a terminal) and terms from a controlled vocabulary (more especially vital when working with standards and conformance documentation; I didn't notice any of that in your current docs but I didn't go through in depth).

@dkfellows dkfellows mentioned this issue Feb 19, 2024
11 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant