Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
Re: Wiki development
Done. Play nice everyone!
Offline
Re: Wiki development
philwareham wrote #278313:
if there is the decision to use Textpattern to power the documentation, most of the codebase/style of .com can be used for .net without any major rewriting (maybe just a few extra page/form templates). That makes ongoing maintenance easy and manageable.
Makes sense. Looking more and more like a Txp install is probably the quickest road to remedial intervention on docs.
Btw, anyone, a very important part of remedial action on content, as it concerns facilitating .com and .net work, is assessing content for ROT (redundant, outdated, trivial) status, what do do about it if so, and where any “keepable” content might need to be relocated (e.g., FAQs in .com to the user docs).
To help with that kind of thing, we (in the content strategy / IA world) typically do an inventory of what exists then audit the status of it for any changes needing made, making good notes for action to take on each item. Such a Textpattern Content Audit has been started (Phil is now document owner). It just needs more eyeballs and contributors making notes in the auditing part. Especially important is the FAQs. There are, by any reasonable standard, way too many, so the idea is to reduce FAQ considerably by rewriting that info in context of user docs. So the idea for FAQs is to:
- Flag FAQs that are already redundant to user docs (indicate where in user docs so it can be confirmed and improved, if necessary).
- Flag FAQs that are no longer relevant (the O and T of ROT).
- Flag FAQs that can be rewritten in context of suitable .com content. I.e., don’t make readers go to FAQ, let them learn in landing copy.
You get the idea. Do the same with all .com content.
Also look at metadata and URL structure. If these are missing (e.g., descriptions) or need changing due to improvements to IA, then you need a redirection plan for those URLs. That’s part of the auditing too.
Once you have your auditing done of what exists, you can then map it to a new IA, including how new content will be a part of that IA.
I can’t express it enough… taking the time to do this auditing first, will speed up the fixing and migration processes considerably. You could be making editorial changes in the wiki now so that part of it is done before migration to a new tool. Logic!
Offline
Re: Wiki development
If anyone makes changes to the wiki over the next couple of weeks, then please let me know. I’ve already exported the ‘installation’ and tag-reference’ sections data from the wiki and am gradually adding those to GitHub – so if any changes are needed to those they should be done in GitHub.
The other sections are still fine to edit in the wiki for now. I’ll keep you posted on which sections I’m working on.
Offline
Re: Wiki development
You can see who made what changes via the contribution scores page, as one way.
Offline
Re: Wiki development
OK, thanks Destry, that’s helpful for tracking.
Offline
Re: Wiki development
Also: the public log and recent changes
Offline
Re: Wiki development
Destry wrote #278310:
“CMS” has always been a stretch for Textpattern (for the sake of search rankings). A web publishing system is more like it. Being able to use the acronym, API, would be a more distinguishing feature to boast. Alas.
Valid observation.
Offline
Re: Wiki development
I’d like to announce a freeze on any more wiki user accounts until it’s clear what the future of docs is; whether it will remain in the wiki, or move to a new platform. If it’s going to move, there’s no point creating more accounts that will rarely to never get used anyway.
Offline
Re: Wiki development
It will move to a Textpattern install somewhere eventually. I made a start on moving the documentation to GitHub for this purpose, if any of the articles you want to edit are already there, then feel free to amend them. I’ll add more pages as I get spare time.
Last edited by philwareham (2014-04-17 11:14:30)
Offline
Re: Wiki development
Okay. No more wiki user accounts, then.
Offline
Re: Wiki development
While were thinking about this, can we confirm/dispute a few more points so everyone is on the same page?
- Are we for sure ending support of doc translation efforts?
- Are we keeping docs editing to a restricted few editors?
- What will happen with the non- user docs content currently in the wiki? For example, all the developer stuff, etc.
- In relation with #3, is there a rough sitemap outlined yet for the new Txp-powered docs?
- Once there is an IA plan for new docs, can we run the wiki and new docs in parallel until the wiki content is fully ported?
My own thoughts on these points…
- We should end translation support because that was the whole point of the wiki, and user doc translation efforts have been pretty much a failed process since day one anyway. I’d also propose a push to those language communities to get their stuff out now if they want to keep it. Most of it will be pretty crude after the migration anyway because so much of the English content will be revised, and especially as we get closer to 4.6.
- I think we should restrict editing rights, for a number of valid reasons, including crowd control, consistent style/tone, accountability, etc.
- One thing that’s always been confusing about the wiki is the mixed nature of content. If we’re going to make this change now, it would be wise to keep end-user docs (what the wiki was really meant to be for) separate from developer docs, community projects, and whatever else landed in there by happenstance. I would really like to see the Textpattern install be end-user docs (core-based) only. Dev docs, for example, might be best left to Github, or something. On that I don’t really care, that should be a dev decision, but the dev content, etc, should not be mixed with the end-user stuff.
- ?? — If there is a rough plan, I’d love to see it. If not, I can probably help there.
- I think having the two sites running in parallel, temporarily, while editors work on the porting would be wise, and a lot easier for those doing the editing.
Offline
Re: Wiki development
Destry wrote #280287:
Are we keeping docs editing to a restricted few editors?
Since the docs are under VCS, they are going to be edited through that git repository. And, yes, anyone can contribute by sending pull requests. Pull requests are then merged as seen fit.
philwareham wrote #280285:
It will move to a Textpattern install eventually. I made a start on moving the documentation to GitHub for this purpose, if any of the articles you want to edit are already there, then feel free to amend them. I’ll add more pages as I get spare time.
I don’t honestly see any reason to use Textpattern for the wiki, when the content is entirely static and comes from VCS.
Textpattern’s doesn’t really work for that with its old-school web GUI based workflow and API-less codebase. I would rather use a static site generators and so on. Good option could be Sculpin or Jekyll, or building small CLI builder (or view bootstrap app) in Symfony.
If Textpattern was modern, used views and so on, and allowed pull in content from where ever (used ORM), we could do anything with Textpattern, but Textpattern is essentially just another procedural CMS.
We could write all that cool stuff, but we can’t even come into conclusion whether we should jump to PHP 5.3.0, or what framework we should use. And yes, we should use frameworks and package managers (Composer). And no, they do not affect end-users as they are downloading build packages with all dependencies already added in. We can’t use ORM or do APIs without conclusion whether we are requiring PHP 5.3.0 or not, and adapting the use of frameworks.
Last edited by Gocom (2014-04-17 09:57:52)
Offline