Issue 7201 - Add links to CMS documentation

Issue 7201 - Add links to CMS documentation

[Vasily Kuznetsov, 2019-01-10 16:24:01]

Hi Rosie,

Looks good. Two questions:

1. Have you thought about putting the links at the top? It's a genuine question
and I'm not sure which one is better, but I kind of expected them at the top and
was a bit surprised that they are at the bottom. One argument that speaks for
your approach (placing the links at the bottom) is that ReadTheDocs
(https://docs.readthedocs.io/en/latest/versions.html) also places them at the
bottom. Still I'm interested in what you thought about these options.

2. What do you think about separating the links from the main text by a
horizontal line ("---" in Markdown)? Perhaps it would make it more clear that
those links are separate from the text.

Cheers,
Vasily

[rhowell, 2019-01-10 20:21:27]

On 2019/01/10 16:24:01, Vasily Kuznetsov wrote:

> 1. Have you thought about putting the links at the top?

I considered it briefly. If it were more like a navigational bar, then I
would've put it at the top. But, I usually see Prev/Next buttons at the bottom
of pages. Also my personal experience using the CMS documentation: if/when I get
to the end of the page, it usually means I haven't yet found what I was looking
for, and that's where a 'Next' button would be most helpful.

> 2. What do you think about separating the links from the main text by a
> horizontal line ("---" in Markdown)? Perhaps it would make it more clear that
> those links are separate from the text.

Good idea! Any preference as to the length of the line? I know 3 or more will
render properly, but a full line (79 or 80?) might look nicer in plain text.

[Vasily Kuznetsov, 2019-01-14 14:12:15]

On 2019/01/10 20:21:27, rhowell wrote:
> On 2019/01/10 16:24:01, Vasily Kuznetsov wrote:
> 
> > 1. Have you thought about putting the links at the top?
> 
> I considered it briefly. If it were more like a navigational bar, then I
> would've put it at the top. But, I usually see Prev/Next buttons at the bottom
> of pages. Also my personal experience using the CMS documentation: if/when I
get
> to the end of the page, it usually means I haven't yet found what I was
looking
> for, and that's where a 'Next' button would be most helpful.

Yeah, makes sense.

> > 2. What do you think about separating the links from the main text by a
> > horizontal line ("---" in Markdown)? Perhaps it would make it more clear
that
> > those links are separate from the text.
> 
> Good idea! Any preference as to the length of the line? I know 3 or more will
> render properly, but a full line (79 or 80?) might look nicer in plain text.

80 would be too long, but otherwise I don't really have a preference. I would
probably use 3-5 or something like that but if you think that more looks better,
that's also good.

[rhowell, 2019-01-14 15:34:10]

Hi Vasily,

5 dashes sounds good. Also, one other question: I noticed that
docs/usage/xml-sync.md wasn't linked before, from the README. Was this
intentional? I added links to it in the README, and on the previous and next
pages, but just wanted to confirm this was right. Also, it was in the docs/usage
folder, and alphabetically last, so I put it last under 'Usage', but wasn't sure
if a different order would make more sense.

Cheers,
Rosie

[Vasily Kuznetsov, 2019-01-14 16:15:46]

On 2019/01/14 15:34:10, rhowell wrote:
> Hi Vasily,
> 
> 5 dashes sounds good. Also, one other question: I noticed that
> docs/usage/xml-sync.md wasn't linked before, from the README. Was this
> intentional? I added links to it in the README, and on the previous and next
> pages, but just wanted to confirm this was right. Also, it was in the
docs/usage
> folder, and alphabetically last, so I put it last under 'Usage', but wasn't
sure
> if a different order would make more sense.
> 
> Cheers,
> Rosie

Hi Rosie,

I guess Tudor didn't link it from the README when he wrote that documentation. I
think linking it is useful and where you put it seems right.

Cheers,
Vasily

[rhowell, 2019-01-17 07:16:31]

On 2019/01/14 16:15:46, Vasily Kuznetsov wrote:
> On 2019/01/14 15:34:10, rhowell wrote:
> > Hi Vasily,
> > 
> > 5 dashes sounds good. Also, one other question: I noticed that
> > docs/usage/xml-sync.md wasn't linked before, from the README. Was this
> > intentional? I added links to it in the README, and on the previous and next
> > pages, but just wanted to confirm this was right. Also, it was in the
> docs/usage
> > folder, and alphabetically last, so I put it last under 'Usage', but wasn't
> sure
> > if a different order would make more sense.
> > 
> > Cheers,
> > Rosie
> 
> Hi Rosie,
> 
> I guess Tudor didn't link it from the README when he wrote that documentation.
I
> think linking it is useful and where you put it seems right.
> 
> Cheers,
> Vasily

Ah, makes sense, thanks Vasily. Anything else, or should I push this?

[Vasily Kuznetsov, 2019-01-17 10:25:42]

> Ah, makes sense, thanks Vasily. Anything else, or should I push this?

You can push it. LGTM