Adopting a style guide for Technical Documentation

style
documentation
(Baptiste Grenier) #1

Yes, but unless for some long/ugly links for me it’s clearer/more readable to see directly the link instead of having to over it to see where it points too, to have an idea of what is behind it… :slight_smile:

clients: document testing Oneclient with docker containers
(Bruce Becker) #2

I’ve looked at some style guides to see if there was some research on this - it seems from my initial browsing that there are differing opinions. Since we don’t actually have an EGI style guide for technical documentation, it might be a good idea to fork one and work on it.

Turning to UX StackExchange, it seems that there is some advice here

One good comment is that the text should make sense if it’s printed out in black and white. To me, this means that footnotes should be used[1]

There is also an SEO aspect :

but this has more to do with the actual text in the page than the href or alt tags.

Anyway, we have discussed this many times before – I’m sure you’ll agree that we could benefit a lot from having a style guide, for technical documentation. I think the IBM Developerworks Style Guide is a really good reference to adopt!



  1. Like this. ↩︎

1 Like
(Baptiste Grenier) #3

Yes I agree that a style guide would be great. Indeed the IBM style guide sounds quite appropriate.

Recently I also came across prettier.io that has support for Markdown and also write-good, and some other “prose linters” that can be used within vim/nvim via the marvellous ALE vim plugin. That won’t allow to enforce a real style guide but can still provide some interesting feedback.

1 Like