[docs] new docs progress

Destry · 2015-07-27 13:00:14

(Thread title has been edited.)

Before we take hammer and chisel to the doc slates — for which the index page is a logical first step, as it gives indication to the organization of content — it would be prudent to briefly talk about audience, scope, and organization.

As I recall from the conversations of old, one of the problems happening with the former .net wiki was that it was turning into a dumping ground for docs of any ol’ nature and audience. But that was not what it was originally created for. It was supposed to be the “end user manual” for the core system, not the plugin developer manual and theme designer manual too. With this new opportunity, I would propose we get back to the basics as it concerned end users and core functionality.

Obviously the core will change a bit in future releases, notably with how themes are handled. But we’re not there yet, so those docs are not a priority yet either. Nevertheless the user docs might not be the best location for specific kinds of docs like theme designing and plugin development. If there’s ever a real plugins site (e.g., .org) and a similar kind of home for themes/competitions, then those locations would be better places for housing their specific documentation types in context. My two cents.

With that in mind, I propose removing reference to any kind of documentation in the new user docs that is beyond core functionality (e.g., extension, custom design, etc.), as well things like discrete tutorials that would provide more clout at TXP Tips, the .com blog, or whatever. User docs should just be basic, out-of-the-box descriptions of core functionality with a few examples (such as you’d find in the Tag Ref pages).

So, if Team Textpattern was in agreement, my first chiseling would be on the index page, refining it to show this more narrow scope of instruction (for the first-time installer/end-user audience type).

Last edited by Destry (2015-08-26 00:01:07)

philwareham · 2015-07-27 13:31:30

Yes please. I’ve already marked a load of docs for the incinerator

Bloke · 2015-07-27 14:20:24

Destry wrote #293727:

If there’s ever a real plugins site (e.g., .org) and a similar kind of home for themes/competitions, then those locations would be better places for housing their specific documentation types in context.

Come the revolution, I agree.

I propose removing reference to any kind of documentation in the new user docs that is beyond core functionality (e.g., extension, custom design, etc.)

You might run into scope issues in the Admin->Plugins panel when describing the steps required to install one. Arguably, the process of installing a plugin (which is, by definition, an extension of the core system) is a core feature, thus needs documenting for the end user. And the installed plugin might well add its own panel to the Extensions area, which is NOT visible out-of-the-box. So to a new user who has found abc_uber_mega plugin, their seamless user experience might be curtailed without at least a passing mention to the fact that plugins can, and routinely do, put their content in non-core locations in the admin UI.

Even if it’s just an orientation exercise, documenting the admin side as fully as possible is important. Some people might have Txp dumped on them from an ex-sysadmin gone AWOL and need to know what the hell the Extensions panel is with all these weird-ass panel names. Granted we don’t want the plugin docs themselves there, but a place to mention the Extensions panel, what it does, how it integrates with Txp, what the three-letter prefixes mean, and so forth is valuable.

Another possible thorn: at what point are the exposed core callback points not end user documentation, albeit for developers? If we laud that Txp is this super nimble, agile, flexible, content management system without even paying lip service to the mechanism of how to make it live up to these claims, we’re selling users short.

I would like cleaner separation of the areas than we do now, for sure. e.g.:

End user, basic docs, largely as you describe above.
Developer docs (possibly incorporating Admin Theme docs since there’s a lot of crossover).
Public theme docs (maybe).

I think there needs to be a space for developer-oriented documentation, the three-letter abbreviation system, where themes (will) reside in the file system and so forth. Farming them out to other sites in the Txp universe might meet the target audience better, but we still need the documentation somewhere in the meantime. Might as well be in its own section of the user docs so we can cross-link easily when necessary.

An example of crossover is in your basic installation docs, you’d say that the steps are X, Y, and Z which will populate the DB with default site content, but if you’d like to alter that by installing a different theme from the get-go, then visit [this subsection] of the user docs for details.

Destry · 2015-07-27 16:54:48

I started a bit but it’s going to be work in progress for a few days. Nothing is being deleted yet and won’t be for a while until we get it sorted better and work through the editing, etc. A ways to go.

Edited: Needless and obsolete words clipped.

Last edited by Destry (2015-08-26 00:00:10)

Destry · 2015-08-25 23:48:46

Destry wrote #293738:

I started a bit but it’s going to be work in progress for a few days.

That was an understatement of the year. But I have been working on it as time allows.

Some updates…

The wiki is now locked off to new changes and user accounts. Sysops can still add info, but will/may only do so to put up signs and redirect traffic, as it were, to key new doc locations. That doesn’t mean every wiki page will have it’s corresponding new doc page. A lot of editorial changes are being made, including consolidation in certain things.

I’m basically working from the new docs ToC, but I’m not going down the line. I’m starting with those doc pages that probably have the most importance for different people, with a few detours, which also happen to be the most time consuming pages. These are the areas I’m working in currently:

Textpattern administration, beginning with the Admin panels and related docs.
Plugin development docs. (Compare with corresponding old plugin dev docs.)
(Tag reference is being worked on by Phil.)

Obviously those are important for two different audiences. I’d like to elaborate on the latter.

Not having looked at the plugin dev docs closely before, I decided to tackle those early, and they’re mostly done with some exceptions I’ll come back to another time. But, I’ve made many changes, more than I list here, thought these should help you see what’s been done so far:

Consolidation and organisation. The old dev main page was just a haphazard list of links (many broken), many of which pointed to other pages with little content having no tight context or order in relation to the main page. I moved content from short pages into the main plugin dev page and ordered sections to more of a learning order as you read down the page (as it made sense to me, but perhaps could be better). In the new Jekyll site, we’re not constrained by wiki page size limits, so we don’t have to spread information out so much. We can always do that later, if necessary, but for editing reasons, it’s better to begin rewriting docs linearly then go from there.

Link ROT. There were broken links (obviously the pages had not been updated in a while) and I just removed them. These links included empty/hopeful wiki pages and external links to zem and Wilshire One websites. Zem’s old site is permanently offline, and Wilshire’s has been since February. I don’t think these things will be missed. Having now read through everything there, I think even I could put a simple plugin together (though it wouldn’t be any use to anyone).

Core functions reference. The noble effort to create a core functions reference, which had hardly begun and would have been worse than a headache to finish and maintain, has been abandoned and won’t transfer. This comes from wise advice from above. Apparently more internal system docs will supplant this effort.

For those who have used the plugin dev docs before, or worked on the copy before, please give things a look where you can and let me know if it’s making sense.

Destry · 2015-08-25 23:49:51

Btw, a word on docs collaboration… I’ve begun to see the light about how useful Github is with docs development, namely with version control and keeping track of issues. When I run into questions, my first point to raise them is with the other docs collaborators in Github. If it goes beyond that, I’ll open up questions/issues here in the forum for more input, like I’m doing now.

When anyone sees a problem in docs, or would like to make a suggestion, outside of specific discussion here, I’d recommend and appreciate if you create an “issue” for it in the docs repo. For certain things this will be the new process, such as for registering plugin developer prefixes. I, or any of the three other current editors there, will follow up with it.

Destry · 2015-08-25 23:55:42

A couple more things:

I) Under the plugin development’s Implementation section, the last two resource links go to meandering old forum threads, which are not ideal docs. I have an issue open about these, but how important are these resources and what can be done about making them more “official” with direct links, if they’re even important?

II) As you can see by comparing the old DB schema page and the new one, the content export didn’t work out very well. All the tables were clipped after just three rows of data each. Further, the table code was mangled somehow (scrambled HTML eggs).

The new page will use Textile tables, and the first short table is now structured that way (thus looks better so far), but I’m not going to manually rebuild all those myself. I’ll do the first one.

It would be helpful and appreciated if others could pick a given table and rebuild it with the following Textile code and the old wiki page data…

|_. Column |_. Type |_. Description |
| data | data | data |

Maybe make it clear here what table you’ll do so others don’t trip over you.

When done, paste your result here, or better yet, if you use Github, start a new github issue and post your code there. I’ll then see they get added and that should finish up all the plugin dev docs pages so far. A not-so-small and significant battle won so far.

If your table has links in the “Description” column, include those as Textile links, but make sure the links are not broken (some are), and either correct them in your code or just drop them. Thanks!

ax · 2015-08-26 08:07:48

Destry wrote #294357:

It would be helpful and appreciated if others could pick a given table and rebuild it with the following Textile code and the old wiki page data…

The Table Data Converter tool can do the trick by simply pasting the text into the input field and toggling the “Output as” dropdown list. For example, the first table:

|^.
|_. Column  |_. Type  |_. Description |
|-.
| ID  | integer  | Unique, auto incremented numerical ID of the article |
| Posted  | datetime  | Publication date and time |
| Expires  | datetime  | Expiration date and time (defaults to 0000-00-00 00:00:00, which indicates that the article never expires) |
| AuthorID  | varchar(64)  | Login name of the author that created the article |
| LastMod  | datetime  | Modification date and time |
| LastModID  | varchar(64)  | Login name of the author that modified the article |
| Title  | varchar(255)  | Article Title |
| Title_html  | varchar(255)  | (reserved for future use) |
| Body  | mediumtext  | Main article text (max 16MB), see also 'textile_body' |
| Excerpt  | text  | Article excerpt (max 64kB), see also 'textile_excerpt' |
| Body_html  | mediumtext  | HTML version of Body |
| Excerpt_html  | mediumtext  | HTML version of Excerpt |
| Image  | varchar(255)  | numerical ID of an image managed by Textpattern or URL of other image |
| Category1  | varchar(64)  | Name of the 1th category associated with this article |
| Category2  | varchar(64)  | Name of the 2nd category associated with this article |
| Annotate  | integer  | Comments enabled? (0 = no, 1 = yes) |
| AnnotateInvite  | varchar(255)  | Text used for inviting people to comment on the article |
| comments_count  | integer  | Number of visible comments associated with this article |
| Status  | integer  | Status (1 = draft, 2 = hidden, 3 = pending, 4 = live, 5 = sticky) |
| textile_body  | integer  | Body markup (0 = raw HTML and text, 1 = textile, 2 = only convert linebreaks. Default = 1) |
| textile_excerpt  | integer  | Excerpt markup (0 = raw HTML and text, 1 = textile, 2 = only convert linebreaks. Default = 1) |
| Section  | varchar(64)  | Name of the section in which this article belongs |
| override_form  | varchar(64)  | Textpattern 'form' containing layout used for displaying this specific article, overriding the form which is normally used to display articles. If left empty, the default layout form is used |
| Keywords  | varchar(255)  | Comma separated list of keywords (often called 'tags') that describe this article |
| url_title  | varchar(255)  | Title of the article as used in the URL for the permalinked article page |
| custom_1  | varchar(255)  | 1th Custom field (plain text) |
| custom_2  | varchar(255)  | 2nd Custom field (plain text) |
| custom_3  | varchar(255)  | 3rd Custom field (plain text) |
| custom_4  | varchar(255)  | 4th Custom field (plain text) |
| custom_5  | varchar(255)  | 5th Custom field (plain text) |
| custom_6  | varchar(255)  | 6th Custom field (plain text) |
| custom_7  | varchar(255)  | 7th Custom field (plain text) |
| custom_8  | varchar(255)  | 8th Custom field (plain text) |
| custom_9  | varchar(255)  | 9th Custom field (plain text) |
| custom_10  | varchar(255)  | 10th Custom field (plain text) |
| uid  | varchar(32)  | Random string used to uniquely identify this article in an RSS/Atom feed. Textpattern uses md5(uniqid(rand(),true)) to create the uid |
| feed_time  | date  | Creation date of the article (when you first save the article, regardless of status)  |

p.

Last edited by ax (2015-08-26 08:08:15)

Destry · 2015-08-26 08:12:38

ax wrote #294364:

The Table Data Converter tool can do the trick

A-ha! So that should help people. ;)

And thanks for that table.

Edit…

Heads up, the converter, according to Ax’s example, spits out

|^.
|_. Column  |_. Type  |_. Description |
|-.
| ID  | integer  | Unique, auto incremented numerical ID of the article |

But that doesn’t seem to render well. It results like this…

^.
|_. Column	Type	Description
-.
| ID	integer	Unique, auto incremented numerical ID of the article
Posted	datetime	Publication date and time

If you drop the |^. and |-. lines it straightens out as needed.

|_. Column  |_. Type  |_. Description |
| ID  | integer  | Unique, auto incremented numerical ID of the article |

Last edited by Destry (2015-08-26 08:26:40)

Destry · 2015-08-26 08:35:21

Btw, Phil isn’t done with the docs’ presentation yet, so things like tables, footnotes, H2s, and so forth will be jazzied up better for improved UX when he gets a chance.

philwareham · 2015-08-26 09:06:30

Yeah, I’m near the end of my crazy summer workload, so I’m just starting to commit bits to the various Textpattern projects again. Yay! Stay tuned.

Destry · 2015-08-27 10:00:20

Hat tip to ax / eliph (same person) who supplied a pull request to fix all the db schema tables. You went above the call of duty. Sorry about not mentioning the wrapper code that Phil pointed out in Github. I was going to do that myself as tables came in to keep it easier for people.

Textpattern CMS

Textpattern CMS support forum

#1 2015-07-27 13:00:14