[wiki] What's on Your Documentation Wish List?

Elenita · 2005-12-11 05:58:56

I have a simple question for the readers and contributors of TextBook: what articles do you wish someone else would write to enlighten you?

Let me be clear: when I mention “someone else” writing said articles, I’m not talking about documentation that you’re hoping gets written before you start because you’re avoiding writing it yourself for fear of boredom. I’m also not talking about the pages that you hope someone, somewhere, writes soon because the manual is so obviously incomplete without it. I’m talking instead about articles that you want but know you couldn’t write yourself.

To put it another way: a wiki’s genius may be in easily sharing whatever knowledge you have to offer with the community. But what knowledge, if you could, would you request to be shared?

As a Textpattern user, I’m asking for a purely personal reason: I want to learn how to write a plugin, only have the vaguest idea about how to get started, and know TextBook would be a great place to learn that information—except, of course, it’s not there (yet). And while there’s no barriers to starting a new page, it’s considerably harder to find a place to ask for one.

But I also have a motive for writing here as a TextBook contributor (albeit a very minor one). Every time I load textpattern.net in my browser, I find some bit of knowledge that I could add… later. I frequently don’t have the time to do it right then, so I add it to my rapidly growing list of Documentation to Write When I Have Time—and then only end up only posting minor edits. And while I’m not trying to disparage minor edits in the slightest, I think that the bigger gaps would be filled faster if we knew what information there’s actually a demand for, instead of just theoretically useful.

In the same vein, I’m not trying to imply that the obvious gaps (e.g., “how to import from [other CMS]”) shouldn’t be filled. If we’re serious about Textbook being a useful manual, those pages are extremely important — and I have complete respect for whomever writes those articles, because I know I don’t have the patience for that sort of thing. Honestly, I suspect most everyone knows that those topics need to be written — but don’t do it because they don’t think there’s an audience for it. Perhaps this thread will prove those assumptions wrong.

If nothing else, I hope responses here give us a better idea of where demand and supply for information match. Or, as the case may be, mismatch.

—————

Note: if any plugin authors think me stupid for not knowing how to write a plugin, don’t reply in this thread with instructions or email me. Do everyone a favor and put that information in the wiki. That’s the purpose of this post, after all.

Last edited by Elenita (2005-12-11 06:27:24)

hcgtv · 2005-12-11 08:10:35

Well, my perspective is from a newbie to Textpattern but I’ve used other Open Source tools for site creation.

More often than not, html pages are distributed with projects, it’s refreshing to see a wiki being used to create a documentation repository.

Since I’m just getting into Textpattern’s usage, I would welcome cheat sheets of certain aspects. Early on, I had to learn Textile and helpful links were posted on the forum to such pages.

Tags would be a candidate for such a sheet, a one or 2 line explanation next to each tag, for printing purposes. I know that each tag has many options but just knowing what’s available and what it can be used for would be great.

When you’re learning a system, overall views are very helpful at first, then going into detail later serves the purpose of a collaborative wiki.

So I would like to see a sort of drill down method, an overview page, a cheat sheet of sorts, that would have links to get us further in. The overviews can be printed as our reference, while the details can be looked up when we need to use that feature.

6sigma · 2005-12-11 15:06:22

> Elenita wrote: But what knowledge, if you could, would you request to be shared?

IMO this is an incredibly important topic at this stage of Textpattern’s development. I’d like to see new documentation written (or older documentation re-written) in a form like So You Want to Learn Textpattern: Plugins or So You Want to Learn Textpattern: Your First Weblog.

I’d like to see this documentation written in what I call recipe form. Many recipes are written with a brief narrative followed by a list of ingredients followed by a numbered list of steps. For Textpattern, I often find that my weak knowledge in XHTML (which links get an “alt” or a “title”), CSS (which is the margin, padding or border) and Textpattern tags combine to prevent real work from actually getting done. (Perhaps we need a Txp tutorial completely free of a stylesheet, then show the styling being added to Txp.)

Here’s a list of documentation I’d like to see in the So You Want to Learn Textpattern series:

plugin fundamentals – installing and adding the new tags in the proper place in your site
reducing the number of plugins your site requires
options for styling blockquotes properly in a Txp site
using CSS with Txp to create a main body and a sidebar of the width and placement you want
styling links differently in articles, titles and sidebars
styling the bullet images in lists differently in articles and sidebars and navbars
how to use Txp to place thumbnail images in your articles
how to add a stylesheet to Txp for printing your articles with links as footnotes
optimum ways to create Txp archives when you have lots of articles
how to make your Txp site cellphone or PDA-friendly
how to add those currently reading or currently listening to features to Txp
Txp sites & …Google Base or Google Analytics or Mint or Flckr or Technorati or Feedburner, etc.
turning Textgarden weblog templates into small business sites
adding horizontal or vertical navbars to your Txp site
how to add a style switcher to your Txp site
an easy way to add Amazon images and links into your Txp articles or sidebar
examples that require you to add a section, page, form or style change
how to add a sidebar feature showing a link to all the articles you wrote on this day in prior years
how to back up your entire Txp site
how to build a web site with Txp that has a complete Txp weblog as one of the links on the navbar
how to add a feature on the main page but not on other pages
how to add a feature that shows up on every page
how to add a feature to one of your backpages (e.g. About or Colophon) but not on the main page
how to add valid and full (or partial) RSS and Atom feeds to your site and its categories

Maybe all of this is spelled out somewhere, but I haven’t found it and my CSS books don’t make the leap over to Txp tags, sections, pages, forms, etc. in a way that helps this nondesigner become a newbie designer.

Destry · 2005-12-12 10:35:24

Good thread. If anyone else ever wanted to contribute but just didn’t know what to write about, well here you go.

From the three posts so far, I see three launchpoints to work into the wiki main page index, which I’ve done as indicated below:

Plugin Development Topics — (Added to Designer and Developer Interests under the “Other Interests” list)
How Do I… Starters — (Added to Getting Started and Official Docs under the “Official/Supporting Resources” list)
CSS Styling Topics — (Added to Designer and Developer Interests under the “Other Interests” list)

The idea of these links is to serve as main page links to topic index pages, which further pursue subject link lists within each respective focus.

The How Do I… Starters page might simply begin as a page with a list of topic sections; each having a one or two sentence description of the subject to be discussed. That would at least give others an idea of what to think about writing. This model would work for the CSS Styling Topics index too. I would caution against making this page a list of every topic under the sun…it won’t work. I would keep it to only topics that users need to get started with Textpattern. And as suggesed, each section should be “short”; and could provide a link to another new page where the topic is written about in fuller detail (the long version). That would be my advice anyway and see how it goes from there.

hakjoon · 2005-12-12 23:27:45

The CSS Styling topic concerns me. I’d hate for Texbook to turn into a CSS technique repository, there are already plenty of books and sites out there for that.

Some of the questions proposed depend on getting TXP setup in a particular way, but some are straight up CSS questions.

Last edited by hakjoon (2005-12-12 23:28:01)

Destry · 2005-12-13 14:01:56

I agree, and I thought the same thing. There’s a ga-zillion Web sites that teach people how to work with CSS. TxP does not harbor some mysterious process for using CSS. I would also go so far as to say this community is not in the process of teaching people how to be a Web designer, per se…that’s the individual’s motivation. However, there is a Layout and CSS Discussion forum here so it might be reasonable to think that certain CSS topics pertaining to strictly TxP components — such as TxP plugins, comments, etc. — might be reasonable. In any case, all I’ve done is add the launchpoint link. You could give it a different label if you want, feel free, but either way I doubt you’re going to see a tidalwave of CSS articles suddenly get written. I don’t think it’s something we have to worry about.

@ 6Sigma: — As simple as it might seem, the odds of anyone writing docs for that long list is very, very small. A stronger approach to documentation is to focus on one topic at a time, like what I’ve done with this draft thread (note the word “Draft” in the topic title); furthermore, and for each draft you initiate, you need to provide some feeder material on your own first, something to start with; like links to relevant information, links to other threads where the idea has come up before, etc. I have to question your claim that you can’t find anything on this stuff, the first search I did for Style Switcher (using wilshire’s TxP bookmarklet) gives me all kinds of style switcher leads. Basically, you need to give others a place to start.

Also, by providing as much feeder material as you can, you bring it to attention that the information is desired by a lot more people than just yourself. Documentation is not necessarily beneficial if there’s no recognized need for it. If it looks like you are the only one interested in a topic, then chances are nobody is going to take the time to write about it. For example, I have to wonder about “<em>how to make your Txp site cellphone or PDA-friendly</em>”. Don’t take this the wrong, I’m not bustin’ your ballons, I’m just trying to give you good insight about how to get the rock rolling effectively.

6sigma · 2005-12-13 14:34:17

Elinita asked: I have a simple question for the readers and contributors of TextBook: what articles do you wish someone else would write to enlighten you?

I answered.

Others have different answers. While writers of Textpattern documentation may not want to offer CSS advice, separation of content and presentation doesn’t necessarily mean that either of those is obvious. The question really becomes one of how much prerequisite knowledge your documentation will require. Appeal to experienced designers only, and a lot of prerequisite knowledge is assumed. Appeal to those who are using Textpattern for their first exposure to site mechanics and design, and you may want to offer some background information.

Will more people want to learn and use Textpattern if they believe they will learn good information architectures, content management and design techniques by doing so?

Or…

Will more people want to learn and use Textpattern if they believe the documentation assumes they already have experience with those things?

Perhaps I’ve missed the point and the objective of good documentation is not to broaden the audience at all.

Destry · 2005-12-13 16:07:22

6sigma wrote: The question really becomes one of how much prerequisite knowledge your documentation will require.

This is a good question, but I think the real question is…when does prerequisite knowledge become out of scope for a task?

What this is coming down to (a basic principle in technical communication) is writing for different audiences. The solution for something like TextBook is to write discrete pieces of content for a particular skill level in mind, that’s the best we can do, and the best approach overall all. From there a wise editor might link the various document pieces together (by way of hyperlinking articles together) in the flow of a given article being drafted.

There’s also the principle of not reinventing the wheel. If you can point to another Web site in the course of a particular documentation article to reference a CSS process already written about, that would be the better way to go. I can’t speak for hakjoon, but that’s what I’m talking about with respect to the whole CSS issue.

Perhaps I’ve missed the point and the objective of good documentation is not to broaden the audience at all.

I’m not sure which point you are referencing, exactly, but since you bring this notion up, and speaking from the point of view of a technical communicator, I would say no, that’s not what the objective of good documentation is at all. The objective of good documentation is to help people do something, to get a task done. The underlying assumption is the tasks being written about are the ones most people want to do.

The latter assumption being very important in community situations like this where nobody is getting paid to write for somebody else. Hence, writing gets prioritized based on what is deemed most needed (or unless someone just takes it upon themself to write whatever they want to). The only way to show what is most needed is for people to point out what has already be requested in the Forum, or to get a show of hands for a new suggestion. I would like to see you rewrite that list, 6sigma, in the order you think is most important, and then let others comment on it. That would be a step in the right direction.

EDIT:

I’d like to see this documentation written in what I call recipe form. Many recipes are written with a brief narrative followed by a list of ingredients followed by a numbered list of steps.

I agree, this is a great model, one that works very well.

Elenita · 2005-12-13 17:08:21

Thanks for the replies, guys.

I’ve been thinking about this, and I think both 6sigma and Destry (and hakjoon) have valid points. On one hand, TextBook can be a valid place for certain strictly Textpattern-related tutorials; at the risk of overusing my own example, I think “writing a Textpattern plugin” qualifies. On the other hand, TextBook is (and has for some time) been designated by Dean as the official manual. And IMO, manuals aren’t really the best place to include a sizable number of HOWTO documents; examples, maybe, but not HOWTO’s. Particularly if the entire system has yet to be fully documented, which is true in our case.

(Of course, it’s entirely possible that I have a narrow definition of “technical manual”…)

<blockquote>Perhaps I’ve missed the point and the objective of good documentation is not to broaden the audience at all.</blockquote>

Speaking as someone who admittedly has a longer history with operating systems and programming than CMS’es, I would assert that broadening the audience isn’t the objective at all. I know of no one who has chosen to start using Linux, Unix, Mac OS X, Windows, Perl, PHP, MySQL, etc. after reading the manual. Perhaps someone out there has done it, but they’re the notable exception and not the rule.

Documentation exists, IMO, to give the user the necessary knowledge to use the system (and how to fix it should something goes wrong), including the relevant background information and warnings about its limitations. I think it can assume its readers have no prerequisite knowledge, but be written in a way that does nothing to increase the user base. Increasing Textpattern’s audience/user-base is something we should encourage, of course, but I don’t think the manual is the place to do it, even indirectly.

Maybe the solution is to have a separate repository for “recipes” and tutorials? I’m normally skeptical about forking a project, especially if the two smaller projects are going to be so closely related (and the community is so damn small!), but I’m leery of neglecting Textbook’s role as official documentation for the sake of “How to do X with Textpattern” articles.

hakjoon · 2005-12-13 19:22:14

I think the “How Do I … Starters” section could server as a perfect incubator for small task specific recipes. If they grow beyond quick and dirty tutorials to become good explanations of TXP concepts they could be rolled into the main page, but I think they could start fairly loose with organizational structure put in later once there is more volume to sort.

Just a thought. I think a lot of the stuff in the Tag Examples forum could fit in there.

mgbales · 2006-01-06 14:39:23

I’d like to leave the meta-documentation discussion (well, it seems much of it left a month ago) and return to the original question, “What’s on your… wish list?”

First, an explanation: neither being a programmer nor a professional Web designer, I’ve been learning textpattern in fits and starts. Often my learning happens like this: I look at the code for my site and I think, “x works, but there must be a more efficient way for it to work better.” When I start asking those questions, I turn to Textbook (to date, not very helpful), or I read here in the forum (more helpful, with many of my own questions already answered so that I don’t have to ask often). In this way, for example, I finally understood how textpattern’s conditional tags make markup more efficient, rather than less (remember: not a programmer!). Likewise, over time I’ve come to realize the value of forms for making life much easier.

My process is slow, perhaps moreso because it’s not driven by necessity. Here’s where my process has been most frustrated.

The documentation is too much without context. When I seek help, I seek a situation which is in some way similar to my own. What occasion would I have, for example, to use txp:popup:http://www.textpattern.net/wiki/index.php?title=Txp:popup_/, which may in fact be an extremely valuable tag, but I can’t tell: the wiki tells me nothing about why I would use it, and it shows me no examples of the tag in action.

Context, to my mind, comes in two forms: justification, explanation, and, for lack of a better word, context itself. If textbook were my editing project, I would require all three of those for every page: first, supply 2-3 possible reasons for said-tag or section to exist. These reasons may exist on several different levels, from a programmer’s wishlist to a designer’s value.

Better explanation—of attributes, for example—further elucidates those justifications and reveals the necessity, not just the name of a tag’s attributes. I figure I don’t need to go into detail about this because this is clearly one of the reasons for the whole revamping of the docs.

The context of context, though, might be most useful of all. I realize that because txp interprets its own tags as good XHTML, linking to working examples, for example, of tags, may seem useless. But I think that, with good explanation for what’s happening on a page, it’s one of the most valuable ways to document the system. I offer txp:popup as my case in point. It has a nominal definition, but no justification why one would want to use a popup (window?) to browse. Its code may be the limits of its use, but isn’t there anyone using this tag who might be willing to write a short, sweet explanation for why they use it, and link to their site?

That’s what I want in my documentation, anyway.

Destry · 2006-01-06 15:23:08

You know the old question: if you wish in one hand and poop in the other, which will fill up quicker? ;)

Seriously, these are all good points, but nothing that hasn’t already been said by people time and again.

It basically comes down to this: people writing. You can make all the wishes and editing rules you want, TxB Editor, Manager, or otherwise, but if you don’t have people willing to write something to begin with, then it doesn’t mean squat.

In my opinion, the whole point of a thread like this is to give people ideas of what to write about. And everyone up to this point has done exactly that; but unfortunately, nobody is picking it up from there. Writers are not dropping in and saying “Mmmhmmm, mmhmm, got it. I’ll have that written by Saturday.” And that’s the problem.

I don’t know how many times I have seen someone say something to the effect, “I’m new to Textpattern, so I don’t feel I can help…”. Well to you people, guess what? You can help, and it’s largely on your shoulders to do so, to lay the foundation for what you want available. Nothing comes for free; you learn in the trenches and then write something up about it. That’s how it goes in open-source. Here’s how it works:

You get a pen and paper and make notes as you learn how to do something you’ve always wanted to do with Textpattern. (Yes, this is the hard part, the grunt part, the part where you have to not be lazy!)
You get a wiki account.
You create a new wiki page (following whatever page creation guidelines exist) and type up a rough draft of your notes.
You make a note in the main page Talk page about your new page.
An editor (likely me since there is no real editor), or someone equally familiar with the wiki, links your page up in the most appropriate place, which of course you can give your feelings about.

As if that wasn’t gloriously helpful enough (and for which you get some warm fuzzies), then something really magical happens. Other people shape the document into something better, perhaps something with more context, because now they see it and it’s easier to know what to do. The true nature of a wiki.

I’m inclined to think the community needs to have a donations pool that members donate funds too, and from which payment is made to potential writers who come up with the best documentation for a given topic. This might be what it takes, and I’m sure if you newbies want to choke it up, the documentation will come more quickly and on target.

Textpattern CMS

Textpattern CMS support forum

#1 2005-12-11 05:58:56

[wiki] What's on Your Documentation Wish List?

#2 2005-12-11 08:10:35

Re: [wiki] What's on Your Documentation Wish List?

#3 2005-12-11 15:06:22

Re: [wiki] What's on Your Documentation Wish List?

#4 2005-12-12 10:35:24

Re: [wiki] What's on Your Documentation Wish List?

#5 2005-12-12 23:27:45

Re: [wiki] What's on Your Documentation Wish List?

#6 2005-12-13 14:01:56

Re: [wiki] What's on Your Documentation Wish List?

#7 2005-12-13 14:34:17

Re: [wiki] What's on Your Documentation Wish List?

#8 2005-12-13 16:07:22

Re: [wiki] What's on Your Documentation Wish List?

#9 2005-12-13 17:08:21

Re: [wiki] What's on Your Documentation Wish List?

#10 2005-12-13 19:22:14

Re: [wiki] What's on Your Documentation Wish List?

#11 2006-01-06 14:39:23

Re: [wiki] What's on Your Documentation Wish List?

#12 2006-01-06 15:23:08

Re: [wiki] What's on Your Documentation Wish List?

Board footer