Forum:Dual template documentation

Forums: Index → Watercooler → Dual template documentation

Note: This topic has been unedited for 7 years. It is considered archived - the discussion is over. Information in this thread may be out of date. Do not add to unless it really needs a response.

Proposal and discussion

Templates on this wiki have their installation described in documentation, as they should.

But, then, these templates will be copied to others' wikis. And then, they will have to be described - in a different context entirely. No Template:SPW, no "How to install", no nothing - the subject is now "how to use".

If we assume that users will copy these templates to other wikis verbatim, as they should, then they should also have documentation to copy verbatim. This documentation should be located at /doc, so that the templates and their documentation can be copied from the same pagename to the same pagename.

What's currently located on this wiki at /doc should be moved to a different location, such as /templatesdoc. Template:Documentation on this wiki can be modified to suit, displaying only /templatesdoc, or displaying both /doc and /templatesdoc in some intelligent manner.

Agree/disagree? I would be happy to undertake this task myself. Henstepl (talk) 00:20, August 18, 2017 (UTC)

Sounds like a good idea, but maybe you should also post the proposal at Forum:Watercooler and I will advertise it with a wiki-wide notice. You should also leave a message with Kirkburn, since he is technically the bureaucrat of this wiki even though he's Fandom staff. -- Fandyllic (talk · contr) 17 Aug 2017 4:28 PM Pacific

Fandyllic's comment copied from Template talk:Documentation in migration of discussion here. Henstepl (talk) 00:32, August 18, 2017 (UTC)

I have taken the liberty of demonstrating how steps 1 and 3 of my plot would play out by creating a modified template for documentation at User:Henstepl and using it to reorganize Template:USERNAME. Now a user can simply copy the unmodified pages "Template:USERNAME", "Template:USERNAME/doc", and copy the JS listed under instructions, and there will be no redlinks besides a category.

I saw no way around the removal of interlanguage links from the /doc subpage, so I removed them. But the parent template still has its own, so - is it that big a deal?

Category:General wiki templates has been removed, unfortunately complicating the situation. This will have to be discussed... I would be in favor of boiling all templates' categories down to the single "Templates" category that still remains perhaps adding to the instruction section if the creation of a category for some type of template is rather obligatory. Henstepl (talk) 07:11, August 22, 2017 (UTC)

Is there anything preventing you from making this new version of Template:Documentation under a different name like Template:Documentation for copying or something like that? If you could do that, I'll create a wiki-wide notice for people to look at the proposal. -- Fandyllic (talk · contr) 24 Aug 2017 9:40 AM Pacific

The procedure

I think that if we go forward, the procedure ought to be fourfold...

1. Remove Template:SPW from play

Currently there is a template at Template:SPW that tells users of this wiki if a page is on Starter Pages Wiki. Nobody is going to copy that template to their wiki, or at least, they shouldn't, because it doesn't convey information useful to wikis besides this one. Yet we call that template in our documentation pages, forcing a gross redlink on other wikis.

The solution is to remove calls to Template:SPW and instead integrate the functionality of that template into a parameter Template:Documentation. Other wikis will have the documentation template but will not recognize a |SPW = parameter... Which is inconsequential.

2. #ifexist template links

We want to link to other templates, and that's fine. But unless they're on Starter Pages Wiki we shouldn't assume that the user's wiki will have them, so we should link to the version on Templates Wiki instead. But even if they aren't on Starter Pages Wiki, then we shouldn't assume they aren't on the user's wiki either, so we should use an #ifexist rule to decide whether to link to the template on the same wiki or on Templates Wiki.

3. Isolate install instructions and move to a new /install subpage; transclude with Template:Documentation

There will be instructions to install many templates. And that is fine. But a user is not interested in including these instructions on their wiki. So, isolate them, and move them to an /install subpage next to the /doc subpage. Display both with our Template:Documentation - when copied, others' Documentation templates will only display the /doc. Henstepl (talk) 03:39, August 22, 2017 (UTC)

Interlanguage links can be placed on the /install page and transcluded onto the template page - and then, they also will not be copied to new wikis. It is unfortunate that for our goals to be met, we would have to remove interlanguage links from /doc subpages... But really, now, are subpage interwikis necessary?

4. Categories

There used to be more categories for templates on w:c:starter, but now there is only exactly one: w:c:starter:Category:Templates. All the others template categories in use on this wiki are liable to generate ugly redlinks... Should we really assume that there will be a "Category:General wiki templates" on a wiki? Should there be such a category?

This part of the proposal may be controversial but I would think it to be necessary for the purpose. I propose that categories other than Category:Templates be removed from templates, or at least moved to the /install subpage from which they will not be copied as the template is copied. There may be some exceptions: Category:Emoticons, for example, is unlikely to have only one or two of its members copied away, but more likely very many, so it should include the category "Emoticons" and instructions to create that category in the /install page.