Tiki product links to incomplete documentation pages
From a discussion on #tikiwiki, edited to remove extraneous content:
<marbux> I had a question for working on doc.tw.o ...
<marbux> I'd like to focus on the pages that are called from the app as context sensitive help
<marbux> dig out the links from tw.o. so there is something useful there if people go to those pages.
<amette> marbux : I think, that some of those links need some attention, too... you should ask franck - he seems to have some masterplan for doc.tw.o ...
<marbux> so the question is whether there is a dump of the doc.tw.o pages that are called from the app?
<sylvieg> marbux .. about your context sentivite help, will it be more simple to simply add a link to tw.org into the empty d.tw.o pages
<amette> marbux : I don't think so... but it should be possible with a simple grep
<amette> sylvieg : why link to tw.o?
<sylvieg> tell my marbux if I am wrong.. your problem is that doc is half tw.o and halh d.tw.org?
<sylvieg> s/half
<marbux> Yes, that is exactly it.
<marbux> You got my attention with that, sylvieg. How is that done?
<sylvieg> manually 😑 but for people who knows tw but don't wrtire good doc like me ...it is easy ....
<marbux> Ah, I see what you mean. I do something like that now when I pop empty pages on doc.tw.o.
<sylvieg> marbux perhaps we can begin a campain .. each time you find no doc on d.tw.o but the doc on tw.o .. send the link to a list or update d.tw.o with the special block
<marbux> But we are going to be redistributing Tiki as part of a profession-specific package of apps.
<marbux> I'm trying to come up with something that will work for everyone.
<marbux> sylvieg, that would help a lot. Maybe start a forum thread on tw.o?
<sylvieg> I am thinking about the mail-in feature (to a list that will fill up the d.tw.o pages
<sylvieg> like this everybody will be able to add something
<marbux> Ah, I like that.
<amette> Ah, now were talking about a reasonable documentation effort! 😊
<damian> the risk is then in turns into a tikiwiki.org II and a complete mess
<sylvieg> if it is only links? do you think so?
<sylvieg> and we have still the editor to rewrite the information but no have no more empty page
<damian> links arent very good in printed documentation
<marbux> It's also getting the research done we need to do anyway to write the new pages
<amette> the mail-in would just be a buffer... to ease it for people to contribute to doc - perhaps flush it every month, so people need to move it over and integrate in the structure
<sylvieg> it is a temporary solution ...
<damian> much better would be to use the pagename external wiki syntax on those empty pages
<sylvieg> ok
<marbux> Or how about a server level redirection for those pages to the d.tw.o pages?
<marbux> That's leaning on someone else'
<marbux> someone else's time.
<marbux> But it is always going to be a problem because documentation is a moving target. Maybe Tiki needs an admin page that lets you map the context sensitive help pages to the server of choice for each page.
<sylvieg> (marbux: is no more moving because nobody knows where to update. I don't know where 1.10 doc goes d.tw or tw?
<luciash> tw.o is for drafts, d.tw.o is for final polished documentation
<luciash> so, sylvieg, both
<luciash> first on tw.o is better
<sylvieg> so tw.o is more as a dev site
<sylvieg> dev + rfe ..
<marbux> So maybe put links to doc.tw.o on the tw.o pages and map the help to tw.o?
<sylvieg> marbux: the page names are not the same between both ...
<luciash> sylvieg: it's a living place
<amette> tw.o is.... hmm... well, rfe goes to dev.tw.o - tw.o is more a space for taking a note about ideas or such... like OneOfManyAPI, Folksonomy or the like... but it's not a good space to do real work, I fear.. 😑
<amette> luciash : yup, right
<amette> luciash : yup, right - for both 😊
<marbux> For just the pages called from the app, how about creating the missing page names on tw.o and collecting links on them including links to doc.tw.o. That way, people could map to tw.o.
<amette> how about making all the links in the app use the {$docserver} or whatever variable?
<marbux> And it would still let us collect the research we need for the pages on doc.tw.o.
<sylvieg> for instance on http://doc.tikiwiki.org/tiki-index.php?page_ref_id=40, I added the tw source.. easy to do ... and at least it is not an empty page
<amette> I would be happy with every link in the app going to doc.tw.o - and if it's just a page with "Help wanted"
<amette> s/and/even
<amette> yes, or such a basic page as sylvie created - dunno, is there a template for it?
<marbux> sylvieg, I think it should include the plain text URLs for those who download the documentation.
<sylvieg> no
<sylvieg> marbux: but we will never know if it is the clean doc or the old one
<sylvieg> or we put the include in a quote?
<marbux> But will there ever come a time when doc.tw.o will be finished? What do people do if they can't find what they need there?
<sylvieg> they don't use tw anymore ...
<marbux> Even before we finish documentation for 1.9.2, we'll be working on documentation for 1.10.
<marbux> The point is that documentation is always going to be a moving target.
<sylvieg> bbl (tell me if there is a consensus on the links back to tw.o .. I will help
<marbux> Will do, sylvieg
<amette> You guys know "eXtreme Documenting"? - just occured to me - going for a smoke - brb
<luciash> well, i vote for to mark external wiki links italicized
<luciash> ''((tw:SomePage))''
(Note: apparently external links on doc.tw.o is not set for tw.o abbreviation or the above would have tried to create a link. I have now marked it for non-parsing so it will not do so when that feature is enabled. — Marbux But note that the np tags aren't functioning either.)
<marbux> That still doesn't take care of people who download the documentation. They need plain text URLs.
<marbux> Or do the links work in the PDF?
<amette> marbux : links can be made in PDF... but not in this one, like it is done right now
<marbux> BTW, I will save this session, try to compress the suggestions, and maybe try to write an "options" document.
<marbux> luciash, on marking the external wiki links italicized, do you know whether that would satisfy accessibility guidelines for the disabled?
<luciash> marbux: which guidelines ?
<luciash> marbux: it's just better than nothing imho
<marbux> I was thinking of the W3C guidelines at http://www.w3.org/TR/WCAG10-HTML-TECHS/
<marbux> Section 3.1 says to use EM and Strong instead of bold or italics
<marbux> And to control rendering through the stylesheet.
<marbux> I agree it's better than nothing.
<marbux> The section might have given a bit more detail. I wonder if a combination works, like [em][b]text[/b][/em]
<marbux> Maybe accessibility is a topic for another day, since those issues affect more than the missing page issue.
<marbux> So is there agreement on this much: put external wiki links on doc.tw.o but italicize them?
<marbux> BTW, syvie, your example page with external links is WAY better than presenting an end user with an empty page.
<marbux> IMHO
<marbux> It also really speeds up the process of writing the page on doc.tw.o
<luciash> a tip by luci: use konqueror and split window vertically when editing doc.tw.o while having the corresponding page of tw.o open in the splitted view
<luciash> also useful for translating
<marbux> I like that
<marbux> I need a user setting in my brain to enable good ideas like that.
<luciash> 😊
<marbux> How about if I clip this conversation, edit out the extraneous, and post it on the forum at doc.tw.o for review after franck wakes up?
<luciash> np, as u wish 😊
<marbux> OK, so be it. Next item on the agenda?