Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
[wiki] User Manual
Original subject title was…
Proposal: A Textpattern User Manual
Overview
It is no mystery that many new users of Textpattern are disgruntled with the lack of ‘out-of-box’ documentation, and though community contributions to documentation efforts are extremely useful and beneficial to many people (generally the tech savvy), the basic, concise information that a user manual provides is still lacking. After some encouraging discussion in the Textpattern Resources site thread, it seems reasonable to again consider the creation of such a user manual, and integrate it into the existing Resources site as Alicson has already conceived. If you go back and read that thread, particularly starting where I first make a post in it, you’ll see that the concept of a user manual is more than just another resource being herded into the pen, it’s a polished, representative publication that complements the amazing product that is Textpattern.
This quick and dirty write-up is the beginning of what hopefully will become a focused effort at producing a TxP user manual. This write-up serves to take the notions raised in the above mentioned thread about a user manual and structure them a bit, add to them, and open it all up for feedback.
Basic Notions for a Textpattern User Manual
1. Foundation:
The manual would be developed based on community feedback and volunteer contributions. The manual would initially be made available online, coexisting with other community resources in the TxP Resources site, and made directly accessible as a top-level option in the main section links.
Update. It has already been suggested that a wiki might be a better platform for this effort. That is certainly a consideration to make, but if so, what wiki and where will it be hosted?
Update. The suggestions are coming in; I’ll try and keep them noted here. MediaWiki, Instiki
Update. MediaWiki was selected. The TextBook staging site is here: http://textpattern.net/wiki/.
Title: The manual needs a short, clever title that falls inline with the current naming scheme of the Textpattern family of products/resources (e.g., Textpattern, TextDrive, Textile, etc.). Below are several suggestions with a corresponding vote tally. Provide another suggestion or vote for your favorite one:
- TextBook (2)
TextManual(1)TextHandbook
Update. 340 thread hits at the time of this edit, and only 3 votes (sad). No point in delaying any longer. By majority vote, 2 to 1, the user manual is now dubbed TextBook. Big ups to Alicson for the dub.
2. Structure:
The manual would follow the principles of a typical application manual, and content would be organized according to the logical flow of TxP concepts as would be optimal to allow a new user to learn and use TxP right ‘out-of-the-box’. (See initial manual structure proposed below.)
Update. Suggestions are coming in, and it seems a wider range of material is desired in the manual. Expect the structure below to expand as it’s realized.
3. Content Creation:
Basic ideas for the creation of content components (sections of the manual as suggested in the proposed structure). Individual content components will make it easier to revise and update content as new TxP releases and/or functionality changes are made.
- Content components would first be filled-in to the structure by using existing TxP documentation resources. Existing resources would be reviewed, combined, and edited to produce a single, concisely written content component for each manual topic. When existing resources are used in the development of a content component, the resources will be referenced at the end of each manual chapter within which they contributed to content.
- For topics where no existing resources are available, content components will need to be written on a volunteer basis. Content submissions should undergo the same review process as for existing resources to ensure consistency in style, tone, and caliber.
4. Presentation:
The manual would follow a style guide for presentation. The style guide would be written-up and made available for community reference, and a CSS style sheet would be created that reflected the style guide rules. Creation of the style guide itself would be based on community feedback. The only base requirement would be that the manual would have an overall look and feel characteristic of TxP’s current branding. Looking into the future, with the potential that the manual would become desirable as a printed resource, the style guide might also take into account a second CSS stye sheet for printing the manaul as well, or perhaps make the manual available as a PDF file that is formatted according to the style guide.
5. [Added] Translations/Localization:
The manual should obviously support users from everywhere, but aside from the translations, everthing else (e.g. presentation) should remain the same, as much as possible (branding aspect).
6. Other considerations?
Proposed Structure of Textpattern User Manual
Does this seem like a logical flow of concepts that would optimally support a new user in learning/using TxP? Are there concepts missing that should be added? Are there sections that need better clarification — Chapter 3 for instance? Let’s have your feedback. I’ll revise this structure based on concensus.
The structure has expanded since first proposed below. To see the structure as it is at any given moment, go to http://textpattern.net/wiki/. The original proposed structure below is struck out to avoid confusion.
Chapter 1: Textpattern Overview
What is Textpattern?What can Textpattern do?Who is Textpattern for?
Chapter 2: Textpattern Installation
Chapter 3: Textpattern Semantic Model
OrganizationPresentationContent
Chapter 4: Textpattern Administration Interface
Admin TabPreferences SubtabSite Admin SubtabLogs SubtabPlugins Subtab
Presentation TabSections SubtabPages SubtabForms SubtabStyle Subtab
Content TabOrganize SubtabWrite SubtabArticles SubtabImages SubtabLinks SubtabComments Subtab
View Site Tab
Chapter 5: Basic Textpattern Setup
Messy vs. Clean URLsBasic Weblog ModelBasic Commercial Site Model
Appendix A: Textpattern Tag Definitions
Appendix B: Textpattern Plugin Availability
Appendix C: Textpattern Extension Basics
Glossary
Implications for Contributions
Creating a user manual is not an insurmountable project, in fact, it’s pretty easy to achieve. It just relies on a good plan of approach and community contributions to make it happen. As implied from the base notions above, here are the kinds of activities that would need attention for moving things along…
(Note: activities are subject to change until the scope of the project is fully worked out, but these seem like stable needs, and by far the most important thing to get in place first is #1, or some other development platform — such as a wiki.)
1. Getting the structure of the manual implemented in the TxP Resources site.
In other words, once a manual structure is realized from community consensus, volunteer(s) will be needed to map the structure into the “Resources” site. This might include creating placeholder articles so that when content components are ready, they can just be added in to their spot. Placeholder articles might simply contain a statement that reads “Content for this section is not yet available, but will be added as soon as it becomes so.” Article titles would simply be the title of the complete section of the manual being written about. This process also makes it easy for editors to go in and make revisions as needed.
2. Getting the manual’s Style Guide created.
In other words, volunteer(s) will be needed to take the style ideas from community consensus, and write up a Style Guide that defines both online and print presentation of the manual. Make the Style Guide available in the TxP Resources site as its own distinct article for contributing writers and designers to reference.
3. Getting the style guide’s associated CSS style sheets created.
Pretty obvious what this is about. There will likely be two styles sheets to produce, one for online presentation, and one for print presentation.
4. Getting the <em>content components</em> produced.
Suggests several areas of activity.
- Contributions to producing content components based on existing resources (reviewing, combining, rewriting).
- Contributions to producing content components where no resources exist (pick an empty content placeholder, write a content component to fill it in; hopefully someone else will review/edit the contribution.)
- Contributions to the review and editing of draft content components for caliber, style, tone, presentation, and most importantly — simplicity. (A content editing stage is what makes a world of difference in the quality of the finished product.
- Contributions to language translations of finished content components.
5. Getting graphics, diagrams, flowcharts, etc. created, as conceivably necessary.
No reason why two or three people couldn’t team up to create a draft content component; one person does the writing, one does the graphics…that sort of thing.
So there it is, the initial outline of thoughts, which hopefully from all the user feedback it’s sure to generate, will pave the way to the creation and timely release of TextBook, or TextManual, or TextSomethingElse…start voting!
Last edited by Destry (2004-12-18 10:18:50)
Offline
Re: [wiki] User Manual
<em>From <a href=”“>this thread</a> Remillard wrote:
<blockquote>“Perhaps during development, a wiki someplace quiet would be a good idea?”</blockquote>
and from the same thread hakjoon wrote:
<blockquote>“I was just thinking that. A Wiki would seem like the perfect place to start the docs. Or maybe a master TOC article that could be used as the starting map and others could submit docs to fill in the areas as separate articles….”</blockquote></em>
I had considered a wiki, but Alicson has made efforts (and logically so) to integrate a user manaul into the Resources site, and I’m just attempting to support that effort, not compete with it.
On the other hand, a wiki site might be easier to follow along with in the beginning, and make it easier to controll the writing and editing. Just as hakjoon suggested, and which was my own input as well, the table of contents (as suggested by the proposed manual structure above) would be the perfect view for the wiki home page, making it “easy to see right from the beginning what the manualâ
Last edited by Destry (2004-12-14 16:31:52)
Offline
#3 2004-12-14 01:43:20
- Remillard
- Plugin Author
- From: Lenexa, KS
- Registered: 2004-05-16
- Posts: 169
Re: [wiki] User Manual
The Trac wiki was deliberately closed because it was getting seriously targeted with wiki-spam.
I don’t know that it ought to be a final location either for docs, but it’s not a bad method for writing, editing, and revision control, etc.
Offline
#4 2004-12-14 14:26:02
- davidm
- Member
- From: Paris, France
- Registered: 2004-04-27
- Posts: 719
Re: [wiki] User Manual
Destry, that’s a great idea, and the work you’ve put up is already impressive :-)
I am willing to contribute, and since you’re in France too, why not translate it once it’s done in english ?
Also I agree on the wiki as the best platform for such a project. I don’t think having a part of Allicson’s excellent site run under a Wiki CMS would be to difficult nor would it fail to integrate. We can adapt the CSS to the wiki and the user won’t even know it… How about that ?
——————-
Isn’t there a problem with the posts dates on TXP’s forum ???
My post is displayed 2004-04-27 while it’s 2004-12-14 here…
———————-
Whhhahhhh, I am either stupid or tired… it’s my registration date !!!
I should sleep sometime… Sorry
Last edited by davidm (2004-12-14 14:41:51)
.: Retired :.
Offline
Re: [wiki] User Manual
You’re just tired ;) And thanks by the way.
<hr>
OK. The first three responders all say wiki.
I’m down with a wiki too, as I am certainly attracted to the writing/editing management it would lend, but…
<ol><li>so long as it’s not going to complicate things down the road with the Textpattern Resources site. </li>
<li>[EDIT] and what about the wiki SPAM problem that Remillard mentioned. Is that going to be an issue?</li></ol>
I’ll leave the mechanics of wiki/TxP integration to someone a little more evolved with TxP principles. (I’m still just trying to get my first TxP site worked out, with two more on the back burner, one of them being mine.)
So I return to this question: “if a wiki, then what wiki and where will it be hosted?”
<hr>
EDIT: Oh, and addressing the French translation point. It makes sense to me to start the manual in English, but do we then start translation efforts in parallel, translating content components as they are first produced? Personally, I think this is the fare way to go, but that would suggest having a wiki spot for each different language, right? (Or am I wrong?) And if that’s the case, which languages do we take into account right from the get-go? Just some thoughts.
As for me translating French, I wouldn’t be doing any favors there. My French is still quite rudimentary (to say the least). Though I might be able to coerce my beautiful better half into lending me a hand, but no promises.
Last edited by Destry (2004-12-14 15:40:11)
Offline
#6 2004-12-14 15:45:03
- zmeigorin
- New Member
- From: Moscow
- Registered: 2004-11-12
- Posts: 6
Re: [wiki] User Manual
> where will it be hosted?
Alicson? (-:
> what wiki
MediaWiki , maybe?
Offline
Re: [wiki] User Manual
As suggestions/votes are made about such things as wikis, the name of the manual, etc. I’ll make good efforts to add them to the initial post in this thread, so it’s easier to see at a glance what the growing concensus is on these topics.
For example, if you direct your attention to the first post and look under the <em>Basic Notions</em> section, you will see that in points 1 and 2 I have started a tallying process for wiki product suggestions and manual name votes.
Alicson: the first vote for “TextBook” was a nod in your direction since you dubbed that label in the Resources site. If you want to change, let me know. (heh)
The first vote for “TextManual” is mine.
So toss your suggestions and/or votes, and I’ll work to keep it updated.
EDIT: And of course keep me honest.
Last edited by Destry (2004-12-14 16:28:10)
Offline
#8 2004-12-14 16:31:14
- Remillard
- Plugin Author
- From: Lenexa, KS
- Registered: 2004-05-16
- Posts: 169
Re: [wiki] User Manual
I would suggest Instiki. It has Textile-Flavored Goodness ™
I imagine this is a low bandwidth sort of thing while in development. I’ll see if I can get it set up on my home machine. (That is to say, I’ve run it on my home machine before. I simply need to get it moved and set up in the general Apache web serving portion of the HD.)
Offline
#9 2004-12-14 16:39:40
- zmeigorin
- New Member
- From: Moscow
- Registered: 2004-11-12
- Posts: 6
Re: [wiki] User Manual
I vote for TextBook. Beautiful, simple, clear.
Last edited by zmeigorin (2004-12-14 16:40:45)
Offline
Re: [wiki] User Manual
Remillard: Do we really want to host this on a home machine? I mean what if there is a problem half way through the effort and …<em>poof</em>! (?) Then everyone will hold a blanket party in your honor ;)
zmeigorin: Done.
Offline
#11 2004-12-14 16:54:30
- zmeigorin
- New Member
- From: Moscow
- Registered: 2004-11-12
- Posts: 6
Re: [wiki] User Manual
Destry, I think Remillard means a test install, to show it in action.
Offline
Re: [wiki] User Manual
Ah, I see. Well then, carry on.
Offline