Documentation: overview/orientation

Bloke · 2019-07-25 21:30:43

[ split discussion from here ]

That’s a great article, bici. Marie’s a fab writer.

Since it’s not available any more, we should probably harvest that content, update it and use it as our ‘overview/orientation’ guide on the docs site. I kinda miss our orientation guide… at least, if it’s still there I can’t find it.

I’m sure Marie wouldn’t mind but if anyone’s in touch with her (Destry?) then please holler. It’d be polite to ask her if we can reuse her content for official purposes.

Last edited by Bloke (2019-07-26 08:34:40)

bici · 2019-07-25 21:36:11

Bloke wrote #318862:

That’s a great article, bici. Marie’s a fab writer.

I’m sure Marie wouldn’t mind but if anyone’s in touch with her (Destry?) then please holler. It’d be polite to ask her if we can reuse her content for official purposes.

Yep!
I’ll ask her as i communicated with her last year, about another matter

bici · 2019-07-26 00:05:17

Bloke wrote #318862:

That’s a great article, bici. Marie’s a fab writer.

Since it’s not available any more, we should probably harvest that content, update it and use it as our ‘overview/orientation’ guide on the docs site. I kinda miss our orientation guide… at least, if it’s still there I can’t find it.

I’m sure Marie wouldn’t mind but if anyone’s in touch with her (Destry?) then please holler. It’d be polite to ask her if we can reuse her content for official purposes.

she is happy to have us harvest and archive her article.
she said: “Haha no objections!!”

Bloke · 2019-07-26 09:08:19

bici wrote #318864:

she said: “Haha no objections!!”

Awesome, thank you.

I’ve since found a worked example and the semantic model overview down in the FAQ section (not in the Administration area where I was looking). Knew we had them somewhere. Both are in need of updating and possibly making more prominent.

I think a dedicated worked example for a portfolio site is great; something like Marie’s article (updated for today’s Txp). Separating some of the introduction stuff would work, too. I can see a need for a “Why Textpattern?” page. Just a short piece outlining what makes us different, taken from Marie’s article with some bullet pointy stuff folded in. That’s good for search engine fodder too.

You know what I also think would be great? An infographic of the Textpattern Semantic Model. Something that walks people through Sections as containers for Articles, each of which may share Pages and Styles. Pages can morph into a bit about Forms, which can lead into a segment on Tags as placeholders for dynamic content, possibly with a nod to Context and the way it is tied to the URL.

Finally, cutting across all this, are Themes being a bundle of Pages/Forms/Styles, and Categories that act as (currently limited) tagging to help visitors find related stuff across any Section. If we’re careful with the wording here and don’t mention the ‘maximum of two for articles and one for other content types’ limitation, when we get some form of unlimited cats/tagging in place the graphic might not need much updating.

I know we’ve tried to represent it as a single image before and got bogged down as it’s so complicated to demonstrate. That’s why a “moving” infographic is better, because it can show the relationships as you move through the hierarchy instead of trying to squeeze it into one area of the page.

I can maybe scribble some ideas down today, then perhaps we can iterate from there to make it better. I’ll also take some of the stuff from Marie’s article and make some skeleton docs on GitHub that we can populate and publish.

Destry · 2019-11-18 19:03:54

This looks like an appropriately titled thread to merge in some more slash and burn from another thread.

As I’ve been dumping a lot of time into working on a ‘trilogy’ of boring resources (baseline project editorial guide, extension guidelines for user docs specifically, and docs collaboration procedures), I thought I’d respond to some things that are relevant now as ever.

For now, the only one published is the extension guidelines for user docs, which contributors probably want to review at this stage, but I’m going back and forth on all of them, and changes are ongoing for a while. Btw, all of these resources will be plugged into the brand and voice index page, soon-ish, a link to which is now in the universal footer.

First let me stoke the coals with context…

colak wrote #315784:

I wish we had a how-to in the docs explaining [flat-file installation] . . . The docs and tips websites are great for tag basics and more advanced tag manipulation examples, but we have nowhere else but the forum to document these wonderful features.

In fact, we have plenty of places to post documentation. And we’re soon going to have a couple more, by look of project repositories. Platform is not the problem. I’ll come back to this.

…thinking aloud about the possibility of adding a section in the docs but I’m not sure if there will be enough interest from the people here to start a collaborative writing effort to make the docs site a more complete reference destination.

We’re getting closer to the problem now — writing/collaborating interest from the people.

But I start getting nervous when I see calls for ‘a complete reference destination’. Didn’t we already have one or two of these once? Yes. All disasters in the end, because a single ‘complete reference’ destination is a bad idea when you have multiple audiences needing specific documentation written at different levels and requiring different degrees of understanding and expertise.

Through the last 16+ years we learned that already, I hope, even if we haven’t yet found that mythic flood of authors.

colak wrote #315790:

What I would like to see developing is a user manual, presenting screen-shots of the installation process (starting with (s)ftp) to the use of tags when designing complex non blog and gallery sites . . . In addition to [those] chapters . . .

Here I can’t help but chuckle a little, because that was exactly the original idea for the wiki I founded in 2004, with help from Remillard and Dean on the back-end. We had a full contents list and everything. I even called it a ‘user manual’ until Alicson called it TextBook. The name took, but not much else. Everybody was fine with this little piece from Dueck, Textpattern Semantics. Nobody wanted to centralize authoring and editing on a user manual because we already had a ‘complete reference’ to it all, Textpattern Resources (aka .org).

Much longer story short, we realized that one site to rule them all was a bad idea, and so was wiki software. And while TextBook eventually became more useful than the Resources site, thanks to a literal handful of dedicated contributors like Bloke and Els, the best thing that ever happened to Txp user docs is what Phil Wareham and team helped make happen by putting it under version control, wiping out all the ROT and rebuilding from what little was good.

Now, if you spend some time reading the user docs guidelines I linked to at top, you’ll see I’m now a believer in the idea that fewer docs are better if the usability of the software itself makes them irrelevant. And that’s how I believe we should approach documentation.

Also note that I don’t prescribe to using the user docs platform for the needs of every project, interest, or audience. Julian is on the right track here, imo…

jakob wrote #315794:

I think we could split some of these things across the docs, tips and maybe even mag articles…

I don’t agree with TXP Mag for user docs and tutorials, but that’s just me. In my view a magazine is a periodical for narrative. Instructions are not interesting narrative. I wish I had the energy and the interest from others to pick up with the mag where it left off, but I don’t, and we don’t, unfortunately. That said, there are plenty of places/platforms for instruction matter:

User docs
Txp blog
Txp Tips

Each is suited to a different kind of length and format. We don’t need a single docs site to rule them all or it will become an IA headache like the wiki had become. I, for one, don’t need that headache again.

Btw, what’s the deal with the Tips site now? Is it under Txp control? Can it be revamped a bit to better align with the brand identity? Can Phil let go of some of of the brand spit and polish work and let others here with design skills have a go at giving it a law-abiding skin? Sounds like a good initiative for collaboration to me. And a good excuse/opportunity for developing brand identity guidelines and demo materials too. Just saying.

As if that wasn’t enough, there will soon be a new Plugins website and a new Themes website.

And here’s where I suspect persuasive discussion with the editing team will need to take place about what will happen in the future. Ideally speaking, each platform should house its own instruction material, specific to the audience the platform serves. I don’t think this makes editorial harder to manage. You either have the people to help or you don’t. Platform has nothing to do with it. In fact, I’d argue that when audiences and their needs are clear, platforms and contexts of use are clear, it’s easier to divide labour and produce the appropriate support information, and perhaps even recruit for it.

For example, I will never maintain developer docs. I can’t. But maybe when they’re orchestrated away from user docs and into a specialized site for developers, third-party developers will take an interest in it. Same with themes. Put themes instructions (excepting the out-of-box basics) and tutorials in the upcoming Themes site, where a showcase will exist, and contests may emerge, and I’ll bet the tutorials will come flying in. LOL. Or not. But at least the info will be in context of the site and audience it’s for.

I doubt that a lot of documentation is needed, in any case. It’s just a matter of finding the key parts that do need written. It’s not a matter of opening up floodgates for whatever anyone wants to write. That’s not really helping core documentation. That’s what Tips is for, or the Txp blog, or your own blog. Lot’s of options. But the core, vetted stuff needs to be focused. We’ll adjust how we use the versioning system to flag topics for consideration, prioritize them, and get able bodies to take them on as time and and qualification fits.

So, let’s use this thread to bounce comments, gripes, etc that I can reflect on and fold into the trilogy I’m writing. Because those will become part of Textpattern’s growing body of brand development resources; in this case about editorial and collaborative guidance on information products.

I don’t know if you can see these Docs Team conversations, or at least some of them, but that’s another place those of us on the docs team (mainly me, so far) hash out things that don’t need a community-wide address.

jakob · 2019-11-18 20:33:34

Without addressing everything you wrote – except to say it’s all pretty good – I’ll just chip in and say that I have taken over the reigns for textpattern.tips from Jonathan and have already done much of a revamp at many levels. I’m working through a way of replacing out of date articles with up-to-date tips while relegating the old ones intact to an archive, because much is no longer relevant.

Was also thinking along your lines with some step-by-step tutorials that aren’t necessarily docs (i.e. official) but walk-throughs of making/doing processes. That’s where I thought the tips or mag site could come in as ways of augmenting the official docs.

Destry · 2019-11-19 09:01:58

jakob wrote #320117:

I have taken over the reigns for textpattern.tips from Jonathan and have already done much of a revamp at many levels. I’m working through a way of replacing out of date articles with up-to-date tips while relegating the old ones intact to an archive, because much is no longer relevant.

Ah, cool. I knew Jonathan had passed it on, but I couldn’t recall the result. The look is less important than the content, for sure. ;) ‘Network’ sites don’t have to be brand-abiding, only the Project sites do. (Though I have a very hard time imagining TXP Mag adopting the universal navigation. Just turn it into the ‘Textpattern Community Blog’ in that case.)

[step-by-step tutorials] That’s where I thought the tips or mag site could come in as ways of augmenting the official docs.

The real problem, as it’s always been in this community, is we want/need the information, but nobody steps up to write it beyond a few quick paras of abstract notes that only the developer or whomever understands. And, historically, when someone has stepped up to write a one-off, glossy wonder — their sole opus contribution — they want to publish it at their own website, where, despite being a hyperlink away, is essentially out of site and out of mind.

The Tips site is a good resource to use because it’s a self-sufficient platform with no more editorial overhead than what contributors impose on themselves before uploading anything. They write, upload, tag. Done. Writing quality, thus resulting user mileage of ‘tip’, is hit or miss.

The mag, by comparison, was an editorial workflow from top-to-bottom, involving multiple people coordinating, interviewing, drafting, reviewing, revising, image hunting and processing, and so on. It required a lot of hands and work to get an issue done before an issue was even published. It’s amazing we got as far as we did, frankly. We had lots of topics listed for writing about, for many issues to come, but buy the end we just couldn’t get the material together. Not enough contributing authors to keep the editors from burning out.

I want to clarify a point I made in my previous post; the mag can certainly have tutorial-like articles, but they’re going to be a bit more elaborate in design, tackle bigger subjects and scopes, and be written from a first-person author perspective. It’s a type of documentation, sure, but it’s not suitable for the type housed in user docs, which is more like technical writing. Mag tutorials are a bit spicier and glossy, and the author’s name is a byline. A big piece on how to convert a WP blog to Textpattern is a good example. Or how to build a store and shopping cart. Whatever.

I was also speaking with the assumption that the prior magazine ‘issues’ model would be retained, in which case a given issue would have three to five articles each, covering (or picking from) the regular subject columns: core, extension, community, design, etc. It could be changed to a single-article publishing model, though, but that doesn’t eliminate all the other editorial needs (and the website refactoring).

So, yeah, pick the platforms of least resistance until you have a dedicated crew of starry-eyed press enthusiasts with plenty of time on their hands.

Was also thinking along your lines with some step-by-step tutorials that aren’t necessarily docs (i.e. official) but walk-throughs of making/doing processes.

I suspect the term ‘docs’ paints a different picture in different heads. For my part, whether it’s a tutorial, a specification, a tip, a FAQ, a dull recital of panel functionality or anything else; if it’s instructional expository, and not content marketing fluff like glossy infographics, or whatever, then it’s documentation.

What’s different in my mind than type of documentation is who the documentation is for and what objective is it serving? That would lend to knowing where a given type belongs and how it should be found. That’s why I say things like, if there’s a plugins website coming, then plugin developer documentation should be easily found and available through that interface.

Themes, as another visible example, being an out-of-box functionality, is suited to being discovered by at least two logical user journeys: 1) user docs as core functionality, and 2) the themes website, as expanded front and back-end themes design tutorials, or whatever. Videos, if you want. Screenshots galore. ;) Information just wouldn’t be redundant at each location. Type and scope of documentation would/should fit the platform.

Maybe it would be useful to say what I do see suitable for development at docs.textapttern.com, because it’s not limited to what is there now.

But first I want to say, one reason Tag docs dominate user docs… Well, two reasons, is: 1) they are critical, workhorse docs. If you can master tags, you can master just about anything, and especially lately with all the new functionality. 2) they have been groomed for years, beginning with with Kusor’s original reference. If people put in a fraction of the time/effort on tutorials as the tag docs have received over the years, we (the community) would not be having this conversation, again. (It seems to come up big every couple of years.)

And let’s not forget how underdeveloped the examples in tag pages are. Most examples are just hypothetical. They show functional abilities, but lack contexts that most people really want and need. Examples are brief and abstract. I’m pretty sure that replacing/expanding/improving examples in tag pages would be a big-win boon to improving user docs for all interests and skill levels.

In fact, this might be a good time to consider extracting all the examples out of tag pages so they can be expanded as more thorough min-tutorials in unique doc pages. For example, you have your given tag page, and down at bottom is the usual section for examples, but instead of the quasi-useful snippets embedded on the page, there’s is a list of links to the expanded example tutorials, where each clearly and completely describes the extent of the example. That would be a significant expansion of user docs and keep interested contributors busy for a while. Lots of opportunity.

Another example is functional shortcodes, where custom functionality can be created with nothing but tags and forms. Those are perfectly suitable for user docs, and some already exist.

So, anyway, I’ve always looked at the boundaries of the docs platform (and the wiki before it), as what a site owner (i.e. site administrator, the primary target audience) can do with out-of-the-box functionality. And only out-of-the-box functionality, that’s the delimiter that prevents docs scope creep from happening. As long as a topic is not about expanding core functionality, is not distracting attention from core functionality (e.g. ‘How to important a WP installation’), and not irrelevancy like rules for theme design contests, or whatever, then it’s qualified for being added to user docs architecture. The question is just where and how, and that’s not a terribly difficult question to answer. We just need to get an idea of what is needed so a proper adjustment to the docs architecture can be planned and made.

I don’t know if this is what I’ve seen people alluding too elsewhere, but I’m not opposed to the idea (not that I’m in charge of design) of a new homepage interface where there are three or four main entry points for the common user journey’s people are usually on (I wouldn’t even know what those are anymore), with tailored 1-2-3 processes under them to walk the user through completing the task. And maybe off to the side, instead of all the current categorical lists that exist, we have a single list for the index pages of each category, where the full scope of content under those areas is accessed, so that those who like the current architecture can still easily find it all. But this becomes a fine line between usability and content marketing, and the homepage design is the least of my concerns, to be honest. The simple lists work.

And, again, I don’t think a lot of new docs are needed. We just need to pinpoint the few key docs that are missing, get repo issues written up for them, and prioritize. This speaks to a visible and understood docs collaboration process, which has been lacking, admittedly, but which I am now addressing with the resources I’m developing. The collaboration procedures will be published in the near future, along with the baseline editorial style guide (usable for any project platform).

And just as we may need a few new good select resources, we might also not need some that exist, or at least as they currently exist. Administration panels docs are pretty stale, in my opinion, and unnecessary in most cases, since the usability of these panels is pretty good. Not perfect, and we want to use docs for where imperfection exists, but the point is, we don’t need to document design for the sake of documentation. I tried to introduce that idea in the user docs guidelines I linked to, but that’s not meant to encourage an immediate removal of those pages, but to start thinking how we can remove what is obsolete, or, better, revise the worthy bits into different types of more useful material.

In the meantime, everyone can start naming needed topics, and we’ll decide if they fit docs. If they do, we’ll get the issues written up. And if they don’t fit docs, other platform opportunities exist. And there will be more. In fact, now is a good time for somebody to be working with Phil about what content should be planned for the Plugins and Themes websites.

Bloke · 2019-11-19 10:32:15

Destry wrote #320128:

Administration panels docs are pretty stale, in my opinion, and unnecessary in most cases

Just want to touch on this. One thing we’ve been guilty of – not just us but software documentation as a whole – is writing too dev-centric compartmentalized content. In my last full-time corporate position I was writing user and developer docs/specs every day for web-based software. That affords a perspective on things like meeting user needs. The audience.

One thing that all the previous user docs (at the company) had in common was they were just panel-based:

The Settings panel Use this panel for adjusting settings. Here are the settings. Setting A does blah, setting B does bloo.
The Records panel shows all records that have been created. Filter/paginate them using the dropdown, and so on.
…

Fine and dandy. It fills part of the user journey because if they click on the Settings panel and don’t understand a setting presented, they can find the section in the manual and look it up.

But it doesn’t fill the other side: what the user is trying to achieve by using the software. In our case, Just Write.

For that, topic-based content offers big wins. I had many discussions with jakob and Destry about this and learned a lot in a short space of time. But the upshot as many will already know is that some (the majority of, I expect) users fire up the admin interface and want to solve a problem. e.g. How do I publish an article? If it’s not immediately obvious in the software and they look through the documentation index and see “How to publish an article” as a topic, that’s more likely to meet their requirements than “The Write panel”.

The topic How to publish an article encompasses the Write panel. Might cover how to use custom fields, which mentions (or links to) information in the Settings panel regarding Custom Field definitions. Might mention the ‘no-widow’ setting. Crosses over into how content is Sectioned and Categorized, which can then lead them into the rabbit hole of Presentation and tagging content. A common thing to include in an article is an image, so discussion – or links – on how to upload images and use them in an article, plus links to the plugins site (when it’s live) for other more drag/drop/automated solutions that might improve workflow. And so on.

So while there’s a sort-of need for top-down interface-level orientation stuff, I feel there’s also a use case for topic-based discussions like the above for common user end-goals. The trick is to combine these with the panel docs in such a way that we don’t end up repeating ourselves on different pages, because that leads to annoying inconsistencies and multiple things to sniff out and update when stuff changes.

I looked into the whole DITA thing and it’s clunky as hell. Or at least the tools to create it, while noble and include big hitters such as Adobe, still make the whole process of doc creation/automation a slog. But the essence of it – creating bite-size nuggets as a sort-of pool of content that can then be threaded / chained together into longer docs to fulfil one or many audience needs, is fairly sound.

If this approach can somehow be mapped onto our processes, that might give us a helping hand.

For example, we don’t have to “publish” everything. If we don’t add a Jekyll header then that ‘doc’ doesn’t become available on the site as an independent resource. Might we be able to use this to our advantage? For example, logically structure the repo so we have “unpublished doc nuggets” that contain specific silos of info – tasks or individual settings, for example – that we can then “include” in longer-form docs that are published.

If we alter the nugget when some UI change occurs in a release, perhaps CI can bubble up to automatically rebuild any doc pages that have included that nugget? I don’t know how capable Jekyll’s Continuous Integration is.

That way, we can build various views into the documentation and structure it as we see fit – one “view” being panel-based, another “view” being topic- or goal-based – but if we’re clever about compartmentalization, the large percentage of the underlying content is only written once and ‘included’, linked with per-doc filler text to bind the nuggets together into a narrative.

Might be untenable, but just throwing it out there.

etc · 2019-11-19 11:49:53

Slightly off-topic, sorry, but in the same domain.

While I have (admittedly) reached a stage when the best docs is the code source, I still find that txp lacks a basic hello-word public theme. The default one is nice and functional, but every CMS has (often many) nice and functional themes. We can hardly (atm) compete with others in this domain. Instead we should show how easily customizable txp is, but the default theme is way too complex for beginners who often fear breaking something.

I think we should provide a very basic theme with the distribution. It could reflect the content of first steps tutorial.

Destry · 2019-11-19 13:30:26

Bloke,

+1 on all that. I think you just articulated our way forward, in fact. Let’s get the community input on a range of high-priority topics/subjects needing tutorialized, then the docs team can start thinking about how to slice and dice existing matter, and eventually show where contributors can help out with authoring missing pieces. Maybe we re-structure the user docs around more of a problem/solution format instead of the ‘type of information’ format it currently has. We just need to figure out what these new problem/solution categories will be, but that should be easier to see after problem/subject tutorial suggestions blow in from the community. 👀

etc,

Good point. So like a ‘Hive Basic’ and a ‘Hive Advanced’. I’ve not really messed with the themes stuff, nor have time to go down this road, but I certainly hope people will step up for a spot in the ‘Themes Team’ where more steps can be taken toward all things themes and the Themes website.

~~Likewise, maybe there should be a Plugins Team too, for more steps toward the information and architecture of the Plugins website.~~ Oh, there is one! :}

I have no idea how far along these websites are, or what Phil is really focused on besides presentation, but I suspect the content aspects of these projects, thus some IA in relation, still need ironed out?

Last edited by Destry (2019-11-19 14:35:40)

Destry · 2019-11-20 10:28:52

etc wrote #320131:

I think we should provide a very basic theme with the distribution. It could reflect the content of first steps tutorial.

Just asking for numbskull reasons… This notion of providing a scaled-down, simpler theme; doesn’t that also mean providing an alternate default template structure (i.e. besides the default blog templates)? Or are you merely suggesting a simpler ‘skin’ as an alternative to Hive for the existing default markup templates?

I ask because, I assume, that if we wanted themes for a photo blog, say, or a small business website architecture, we can’t just make a theme for that to share with people, it requires them also having the same site architecture or the theme won’t fit/work. Right? I mean, you can’t just rely on sharing a theme package to change a site architecture… or can you? Maybe I’m looking at it wrong?

Bloke · 2019-11-20 11:37:25

Destry wrote #320134:

if we wanted themes for a photo blog, say, or a small business website architecture, we can’t just make a theme for that to share with people, it requires them also having the same site architecture or the theme won’t fit/work. Right?

Nope, not necessarily. The beauty of the theme system we have is that it bundles up Pages, Forms and Styles (and soon, other assets after we do a little more core tweaking) into a standalone area on disk. You can import them into a parallel theme in your site, preview them on your live content and then when you’re happy, apply them – make them live – on any Section(s) of your choosing. Mix and match to taste.

Textpattern CMS

Textpattern CMS support forum

#1 2019-07-25 21:30:43