Refactored Doc standards #2481
Refactored Doc standards #2481
Conversation
|
After writing some docs it feels painful to add links. For instance, if I want to write something like "you can read more here". Is there a way writing like: |
| shorthand); | ||
| * Inline hyperlinks are **not** used. Seperate the link and their target | ||
| definition, which you add on the bottom of the page; | ||
| * You should use a form of *you* instead of *we*. |
There was a problem hiding this comment.
How about an example below all of this that shows these rules in action (as much as possible).
There was a problem hiding this comment.
I like that. I need to think of a good example, it's hard to put most standards in one example without the example being to dummy... :)
|
Very nice changes Wouter! Don't forget the map and index changes for the new doc. I have no problems with the 3 items you listed above - we're already been doing these things, I think it's great to formalize it. |
|
@pvolok I had a look into the ReSt and Sphinx specs, but it's not possible. The only thing that's possible is using anonymous targets, but that makes the doc even unreadable :) |
|
@weaverryan I added an example, fixed some things and squashed the commits. It's ready for merging now |
I spoke the CMF guys (mainly @dbu ) this weekend and they are going to follow our documentation standards. Now it's used in more project, I've moved it outside the overview document and inside it's own document.
There are also some other things which needs some discussion (things that are added in this PR are things that I and the CMF guys like to see in the standards, but if people are -1 for it, it gets removed):