Suggested page structure: Page title - page name
The KDE Documentation Primer - Documentation Primer # ToC, everything else is a direct subpage of this
What about the breadcrumb, though? Is it possible to set it manually?
Do we need to change the breadcrumb? Are we flattening too much? I'm thinking something like
etc. - but no deeper than three levels
This model matches what happens on many sections, too.
The main structure, where more detailed structure is necessary, should use PrevNext to guide users. With that in place, I don't think changing the breadcrumb is necessary.
Or am I missing the point?
My suggestion was not meant to apply to manuals generally, only to the Documentation Primer, which has some very long page names as it is. I agree, that in general we shouldn't flatten too much.
In the Primer, only the Appendix has been flattened. Should we use Appendix/Markup in stead of just Markup etc.? It doesn't add too much, so maybe it's a good idea.
More important, though: Do you think that it is a good idea to shorten page names as I have proposed, fx just 'Markup' rather that 'General KDE markup style guide', or will it confuse our users?
Not sure. How do you see the Primer fitting in? Will it replace some of the existing help pages? Just asking because the purpose will dictate some of the answers to your questions 
It seems to me that there must be some visible way of navigating linked pages. That could be by breadcrumb, by PrevNext link, or by explicit links, depending on context. Only two things count - it should fit the context and it should be clear to the user. Once a decision has been made about the best method in any context, then we encourage contributors to stick to it.
I much prefer short page names, as long as its context clear to the reader. Explicit links, such as in the created index pages, can and should, IMO, have explanatory text where any misunderstanding could occur.
It's a pity our next sprint is some months away as it would be easier to sit down together on this
The Primer is about docbook, so it can't replace our guidelines. If fact working with the Primer, it struck me as horribly complex and not helpful if we want to attract non-technical writers.
As to links, the Primer has PrevNext links and a ToC. Perhaps the breadcrumb doesn'n matter as much then?
The current pagenames in the draft version was dictated by the title of the respective sections. They were often quite long. Now that we know, that page names and titles doesn't have to match, I think it is a good idea to shorten page names. That will render the auto-generated breadcrumbs a bit cryptic, but we have a ToC and PrevNext links, so I feel navigation should be easy enough.
Perhaps we should have short page names but use the complete page name as link text in the ToC and PrevNext?
If it is possible, perhaps it would be a good idea to turn off breadcrumbs for those pages?
At least we'll gain some experience and hopefully learn something from our current manual projects so that we can lay down some really good guidelines at the sprint
The Primer is about docbook, so it can't replace our guidelines. If fact working with the Primer, it struck me as horribly complex and not helpful if we want to attract non-technical writers.
As to links, the Primer has PrevNext links and a ToC. Perhaps the breadcrumb doesn'n matter as much then?
The current pagenames in the draft version was dictated by the title of the respective sections. They were often quite long. Now that we know, that page names and titles doesn't have to match, I think it is a good idea to shorten page names. That will render the auto-generated breadcrumbs a bit cryptic, but we have a ToC and PrevNext links, so I feel navigation should be easy enough.
Perhaps we should have short page names but use the complete page name as link text in the ToC and PrevNext?
If it is possible, perhaps it would be a good idea to turn off breadcrumbs for those pages?
At least we'll gain some experience and hopefully learn something from our current manual projects so that we can lay down some really good guidelines at the sprint
Family affairs have kept me busy this last few weeks, so I feel I haven't been very helpful in this respect. Sorry about that. I'm not sure that it's possible to turn off breadcrumbs for a page or set of pages, but I'll try to find out.
KDE UserBase Wiki 