[Freeswitch-docs] Meta Pages? Meta Pages

[Bote Man]

I struggled with this at first, but the search facility on Confluence is not too bad; it's no Google, but a sensible choice of search term can turn up related results wherever they appear in the Table of Contents pane.

The other, more important, attribute is the labels (tags) on each page. Those are even better than meta-pages! Click on a label and the result is a meta-page showing all pages containing that tag. I encouraged people editing pages (and in the past copying them from the old wiki) to assign labels from the list of those already established, but I note that this was not often done. Now, we don't want so many labels that they become unmanageable, but they can tie together related pages regardless of where they are. This is a huge effort because each page must be examined and the longer ones take some time to digest simply to decide what labels to apply. But it's so useful in the long run, as you point out.

Lastly, the Table of Contents pane on the left is merely a serving suggestion. It's good for coarse-grained organization, but the above tools are best for relating pages together, I think. So I wouldn't sweat the ToC too much. I think pages discussing topics that are peculiar to a language or process should be children of those languages and processes. The main configuration tree should deal with overall configuration of FreeSWITCH when first getting started with it to rush it to a working system. Then tweaks to the platform can be made using the other pages as needed. (If we overthink it, the entire wiki is about configuring FreeSWITCH so we really need to be more specific than that :-) 

I had suggested mimicking the software development cycle by freezing the existing docs and starting a new revision to match the current revision of FreeSWITCH. Copy over pages that are the same, edit new pages to reflect changes between then and now, and forget about pages that are deprecated. Confluence supports this, and in fact Atlassian does this on their own documentation Confluence site.

Anyway, that's my take on it.


Bote Man



-----Original Message-----
From: Freeswitch-docs [mailto:freeswitch-docs-bounces at lists.freeswitch.org] On Behalf Of Ryan Harris
Sent: Friday, 26 January, 2018 06:37
To: freeswitch-docs at lists.freeswitch.org
Subject: [Freeswitch-docs] Meta Pages? Meta Pages

I hope we can address the documentation clutter before we get featured on an episode of Hoarders :)

The natural and intuitive way to address the situation is to try to move the existing pages wherever we think they should go. However, it's not entirely clear *where* they should really go.

Think about configuration. Do we include information about serving configuration from the SWIGed languages in the configuration section? Or do we put those in sections dedicated to specific programming languages.
Often the sections can't be about one specific thing by necessity.

It's a dilemma. And, right now, it would be destructive to try to reorder the pages beyond what's already been done. It will just make the documentation inconsistent and more likely cause confusion.

Instead, I'd like to propose the idea of "meta pages". The idea is that their only purpose is to link to other pages.

In the XML metapage, we link to *all pages* that discuss XML. In the Lua metapage, Lua. Ad infinitum.

These pages, I think (I hope), will be able to help us find a natural and logical way to organize everything. I'm going to start working on it now.

Tell me what you think!

ry


_______________________________________________
Freeswitch-docs mailing list
Freeswitch-docs at lists.freeswitch.org
http://lists.freeswitch.org/mailman/listinfo/freeswitch-docs