Style Guide issues

[david-a-wheeler]

I have some recommended changes to the style guide:

• Please don't require yelling-case in the title. It's a pain to read, and it loses information because in many names the upper/lowercase is important (e.g., OpenSSL, OpenSSH, etc.)
• The heading levels are busted. Title at level 1 is fine, but the next subsection should be level 2 (##), NOT level 3 (###). This malformed leveling will screw up many systems, including default CSS and accessibility systems (accessibility systems use heading levels to help the blind or those with significant sight issues). AI systems can work around this but still prefer correct markdown.
• Why do the headings end in ":"? They shouldn't. Usually colons at the end would be forbidden, e.g., markdownlint rule MD026 would forbid it. I recommend forbidding punctuation at the end of heading, and fixing the files to match.
• I suggest enabling markdownlint, configuring rules as needed (but as much as possible accepting its defaults). That will find LOTS of markdown issues for you, and make it easier for other systems to ingest the results.
• The "Name:" formatting is busted. Normally adjacent lines in Markdown are merged. This isn't how you're supposed to do this in Markdown. Put a blank line between each field, turn it into a bullet list, make it a Markdown table, or fix it some other way.
• In the code snippets, don't include "vulnerable file...." in the code snippet, that's in the wrong language. For example, that text isn't legal C.

[abuttner]

Thank you. I think the root of these concerns comes from the fact that the case studies started as PDFs and we then needed an easy way to release to the public. GitHub and markdown solved this challenge, and we used markdown to try and replicate the visual layout we had in the PDF. For example, we felt that heading level #2 was too large and that level #3 was more visually appropriate. Also, the code snippets aren't going to be valid code regardless given the line numbers. We are using the markdown code block for the visual part, not to represent valid code per say. Maybe this was a bad choice on our par? We weren't concerned with following proper markdown as we were more concerned with how the case study looked. I do think some / all of these suggestions can be implemented, but I would love to have more discussion.

[david-a-wheeler]

Discussion would be great!

I don't know what you're using to generated the PDFs, but most PDF generators provide many controls for formatting. In pandoc, for example, you can set the base font, and for more control you can provide your own latex template to control things like the heading font sizes.

For HTML, of course, the whole point of CSS is to let you give a few simple commands and you can easily control what things look like.

I think you're better off using the correct heading types, and then telling the system what to make it look like. It works much better for accessibility in particular; see: https://www.w3.org/WAI/tutorials/page-structure/headings/

[david-a-wheeler]

P.S.: You can shift the 3-levels to 2-levels, and remove the extra colon at their end, with this:

perl -p -i -e 's/^### (.*):$/## \1' */*.md