[wp-docs] WordPress Help Manual on WP Academy (James Gill)

Tue Sep 25 12:55:13 UTC 2012

Again, it's not a lack of understanding.

I've previously pointed you to where a lot of work was going on with the
user handbook.

Specifically you may wish to read this post:
http://make.wordpress.org/support/2012/08/post-hoc-ergo-propter-hoc-approaching-and-defining/

where we have been discussing this very thing. Indeed, the whole Support
blog is full of posts awaiting your input.

There is now a core Support & Docs team, with Mika (Ipstenu), Esmi and
myself as leads. We've been having ongoing discussions as to how to best
approach documentation, while actually working on docs and support, and we
also have a weekly IRC chat that you are more than welcome to attend and
take part in, where there are a number of other professional documentation
and support people involved. The chat is on Thursdays at 5pm Eastern.

You may have read before the WordPress is a meritocracy. We judge user
contributions by a combination of the quality of someone’s contributions,
and their level of interest/time commitment will determine how much
influence they have over decisions.

Over the past few years that I have been involved, the topic of software
for support docs has come up time and again, but the overriding immediate
need is writing and editing the docs to begin with.

The USer Handbook is being written with WordPress - which we both can agree
is easier to work with than the Codex and should not slow down
contributions. We'd be happy to make you an Editor and you can get right to
work as soon as you let me know which parts for the user handbook you'd
like to edit.

Andrea

On Tue, Sep 25, 2012 at 9:26 AM, Marc Beneteau <docs at manifesting.net> wrote:

> James, by "Winhelp clone" i mean any system that provides the Winhelp /
> Javahelp functionality.  This is the way that virtually all professional
> software is documented and there is a reason for that (which you know about
> since you work in this area) -
>
> - Expanding/collapsing table of content (TOC) in left frame, any depth
> (helps user understand where they are in the content hierarchy)
> - Search and Index tabs in left frame TOC
> - Hyperlinking to any topic in the main window opens up the left TOC for
> that topic (again, helps user understand where they are in the content
> hierarchy and keeps a trail)
> - Easily add rich content such as images, videos, and toggles (image
> thumbnails that popup to larger size or else blocks of text that can get
> expanded)
>
> I have an idea for doing this via a WordPress theme / plugin combination.
> It's a rather exciting idea to me.  Once again if anyone else likes this
> idea and wants to participate you can email me marc at wpacademy.tv
>
> To note that the usage or existence of a high-quality documentation
> platform does not guarantee the generation of high-quality documentation,
> but in my case, I can certainly say that it helps with motivation.  I
> personally find it very hard to work in Wiki (images and rich media are
> particularly cumbersome, with the results that we see) and IMHO this is the
> main reason that WordPress documentation lags way behind the WordPress
> code.  I totally agree "find clear specific answers to specific problems",
> the answer to that problem is Winhelp, and particularly Winhelp in
> combination with "Tooltip help" or help topics that are linked from each
> relevant dashboard page (which is the next iteration of this, I think)
>
> I have to say I am a bit frustrated by lack of understanding / support of
> this idea in this forum.  Perhaps (for sure), this conversation started on
> a different topic, and perhaps this is not the right forum for new
> development suggestions as y'all working really hard to support the current
> structure.  What I am suggesting is that the current structure is not
> optimal and that we can do much better. I would argue also that I can speak
> authoritatevely about this since I make quite a good living providing
> Wordpress documentation, which I am willing to contribute to Codex (but not
> within a legacy platform as it would be too much work for me for
> insufficient result)
>
> Thanks
>
>  On Sun, Sep 23, 2012 at 1:31 PM, James <james at thinkhuman.com> wrote:
> >"But I've been seriously thinking about this, what needs
> > to happen (again IMHO) is an open-source Winhelp-clone system powered by
> > WordPress, that would be equivalent to my semi-proprietary system see for
> > instance:
>
> I'd recommend almost anything *but* a "winhelp clone". For me, a
> platform-specific format (especially Windows) both goes against the spirit
> of WordPress and is a cumbersome, anachronistic way of doing things.
>
> I've developed Windows help since--well, since there was a Windows. I've
> also created technical documentation for 20 years or so. Tool-wise, the
> answer is always "what creates something that helps the user be the most
> successful?" I think the answer can be provided with many tools, including
> WordPress or a wiki.
>
> If I were to pick one thing WordPress users likely want most, it's the
> ability to search and find clear, specific answers to specific questions.
> And, if I were to change only one thing about the Codex, for example, I'd
> add more visuals.
>
> -james
>
> _______________________________________________
> wp-docs mailing list
> wp-docs at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-docs
>
>

-- 
-- 
Andrea Rennick, http://wpebooks.com and http://ronandandrea.com
Co-author of WordPress All-In-One For Dummies http://rml.me/aio
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.automattic.com/pipermail/wp-docs/attachments/20120925/3fd5de40/attachment.htm>