On 10/17/2017 07:49 PM, Robert Kratky wrote:
2017-10-17 19:44 GMT+02:00 Matthew Miller <mattdm@xxxxxxxxxxxxxxxxx>:
On Tue, Oct 17, 2017 at 07:09:32PM +0200, Robert Kratky wrote:
The latter should ideally happen hand in hand with content
conversion/creation. For all other content, it is a lot of work but
not necessarily difficult. I imagine a three-day FAD with five
dedicated people could accomplish it.
Okay. Which people, where and when? :)
Well, the modularity needs to come first :-/ We're trying to think of
ways to get more people involved, but it won't be overnight. This is
the sort of work that could really use a full-time person.
As for the tagging -- when it comes to that -- I would volunteer, but
let's not get ahead of ourselves.
If anyone wants to start on that, you can try to think of a list of tags
that:
* is specific enough to make the sidebar less than completely useless
(e.g. 50 pages tagged as "Installation" and nothing else would mean that
a page on the summary hub in anaconda GUI would be shown as related to
things like "how to build your own image" and "how to set up PXE boot" -
you don't want that)
* isn't specific enough to prevent you from actually producing the
"related content" sidebar - there needs to be a lot of overlap
* contains a reasonable amount of tags - not more than, say, 20 (even
that seems like a lot), because otherwise if there are more, nobody will
remember them all and so they won't use them and the whole exercise
becomes pointless. Ideally all available tags would be visible at all
times and you'd just drag&drop or something like that from a list.
Asking people to type them out won't work
* covers every topic we need from the start (and yes, we absolutely do
need to cover everything from the start, because if you add extra tags
later, it means someone has to go and determine if the new tags apply to
any existing piece of content we already tagged before, and that's just
not going to happen)
You could also try to find a way to ensure people actually use these
tags and do that correctly every time, because once people start messing
it up, over time the whole system becomes about as useful as the example
in the first point. That goes beyond "hoping it gets caught in peer
review". Again, someone would then need to revisit existing content and
ensure all tags are correct, and again, noone's going to do that.
Really, I don't understand what's so difficult about just *linking* to
other content that's directly relevant to what the user is currently
reading. "I'm writing about how to write your own systemd service?
Surely a link that explains what the hell systemd is and a link that
talks about systemctl status/enable/disable/start/stop would be useful
here". That way *only* relevant links are displayed at all times,
because a human, not essentially a weighted random number generator,
added those specific links to those specific places there. It's a
thousand times more useful and you can do that with no additional tooling.
Now, here's something I believe would be infinitely more useful -
extracting "tags" from content:
* Use some semantic tags like [filename], [package], [service], etc.. We
still need to define these first and stick to them, though, so this
shares some problems with the manual tagging scenario above. However I
think it's much simpler to identify semantics we want to track than it
is to define something as abstract as tags, especially since DocBook
already had those semantics.
* At some point during build, something would grab a list of all these
tags (and their contents) by page
* Offer that in the sidebar. E.g. you're reading something that mentions
[filename]**/boot/grub2/grub.cfg**, here's a list of other pages that
also talk about that filename.
That still doesn't come close to direct links to directly relevant
content, but at least it doesn't require us to maintain a fragile
database of tags since everything after using the semantic tags (for
which we can provide snippets) happens automatically.
Petr
Robert
_______________________________________________
docs mailing list -- docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx
_______________________________________________
docs mailing list -- docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx
