English > Feature Suggestions

Integrated Help Forum

<< < (3/4) > >>

rick.ca:

--- Quote from: CAD on August 31, 2010, 12:02:55 pm ---Is this not what you are advocating?
--- End quote ---

Yes, but it's also intended to be the opposite of "unwieldy." What is it about what you are imagining that is unwieldy?


--- Quote ---Unless the moderator (you) reads every single post in a topic and takes relevant info out and puts it into 1st post, then users have to read through potential crap to get to the bit that explains how to do something...
--- End quote ---

This is circular/false logic. You're assuming topics are not going to be maintained, and therefore users will have to wade through many posts to find the information they need. Why can't you imagine the thing as I've proposed it? Initially, a topic would consist of the best available documentation we have—perhaps something compiled from existing wiki content. Obviously, users will then instantly find the information their looking for. And, if they need to ask a question about that material or suggest an improvement or addition to it, they can do so right there. Then, regardless of who is going to make the necessary change or addition, it couldn't possibly be easier than it would be with this arrangement—where the help topic in question is always the first post in the thread.

But the ease of maintenance is secondary to the main benefit and purpose of the proposal. The help file could be a significant gateway to the forum for users—particularly those who need help but are reluctant to participate here (or just expect to be able to find the help they need on their own). This should be a highly effective way to bring the "help seeker" here and say to them, "Here's the information available on this topic. If you need any further assistance, please ask." Even if this is not going to be as pretty as alternative forms of help documentation (and it's not), it's very well suited to our circumstances. I think many would even consider it revolutionary. A tiny little freeware app—with help fully integrated with its user community. Awesome!


--- Quote ---...and it means a lot of work for moderator (you) in editing posts.
--- End quote ---

This is another reason why this is a "trial balloon." I'm not going support or take any action on anything that simply means more work for me and is of no interest to anyone else. I already do more that enough here. I think it's a good idea because it's an effective and manageable solution to the documentation problem, and would improve the synergy between the application and its user forum. But it's not going to work if I'm the only one who believes this. It's also not going to work if there's even the expectation I (or someone like me) is going to maintain it. Restricting the ability to modify posts to moderators is a necessary evil. That doesn't mean there can be only one moderator. Moderators are designated by forum. For this help forum, I would suggest any experienced user should be made a moderator simply by asking.


--- Quote ---But i would like to see a small trial to see if it would work in principle.
--- End quote ---

A trial can be used to see if something works in practice, but we're not there yet. We're still discussing whether it will work in principle. I'm certain I've described the principles well enough already. You've already made a good case for the impact of another principle. The idea may fail simply because users don't understand it, or believe another approach would be better and therefore choose not to support it.

I see no reason why nostra would choose not to implement the help file capability. Even if the context hooks are not feasible or too much work, there's no good reason for not adding the simple capability of launching an HTML help file from the program. Once that is done, starting with a small trial is probably the way to go. It's already clear this will work "in principle." The significant part of the experiment will be to see if users embrace and support it. If it fails, the program will still have a help system. There will still be the option of adding a few links to a view online tutorials, or put such things directly in the help file...


--- Quote from: nostra on August 28, 2010, 11:39:31 pm ---I think I will implement some kind of tutorial or online help in version 1.
--- End quote ---

The reason I'm bringing this up now is the release of version 1 is going to require a relatively massive update to the help documentation. It seems highly unlikely that's going to happen by people volunteering to update the wiki. Or create another one. This is an opportunity to do it in a way that's more likely to be effective.

I have no idea when version 1 might be released. If it's some time off, and we have some agreement ("in principle"), it may make sense to do a trial in advance. That might include...

1. A 0.9.9.x release in which the help file capability has been added.
2. The addition of a new "Help" forum for which anyone interested in getting this going is given moderator permissions.
3. The creation of a sample/abbreviated table of contents for the help forum—where each item is linked to a separate topic.
4. The creation of a help file with an identical table of contents—where each item is link to its corresponding forum topic.
5. Moderators could start by "dumping" existing wiki content into the application topics. These could then be discussed—if necessary—then edited into appropriate form, cross-indexed to other existing topics, etc.

If we had the basic structure in place, it would be a much less daunting task to document the changes in version 1. Version 1 could also be released with a help file that at least got users into the help forum. Or, nostra would have the option of adding topics for brand new features. These might initially be just very brief descriptions (the kind nostra is famous for), but would be a cool way to inform users of new features, while providing a permanent link to their help topics. In many cases, fuller documentation would naturally (and probably very quickly) evolve from users asking questions and others explaining how the feature works and how it can be used.

patch:

--- Quote from: CAD on August 31, 2010, 12:02:55 pm ---
--- Quote ---You participate enough here to understand how the forum software works
--- End quote ---
Yes and this is why I don't think it is an adequate tool for a help system. Unless the moderator (you) reads every single post in a topic and takes relevant info out and puts it into 1st post, then users have to read through potential crap to get to the bit that explains how to do something and it means a lot of work for moderator (you) in editing posts.

--- End quote ---

Yep that is the main issue with maintaining a dynamic document in a forum. Only moderators and the thread creator can maintain the opening post. Works fine if the thread creator owns and wants full responsibility for maintaining it. However it actively discourages peer co-operation in favour of a hierarchical approach.


--- Quote from: rick.ca on August 31, 2010, 08:11:26 pm ---
--- Quote from: patch on August 31, 2010, 11:58:00 am ---Having the primary entry into the wiki pointing to the contents page would go a way to fixing the current one. Better still if a search box was added to it.
--- End quote ---

As I've already said, the purpose of this topic is to discuss a completely different alternative to wikis. If you would like to discuss how to fix the wiki, please start another topic.

This does, however, illustrate the need for an alternative. The author of the wiki recognized the need for this "entry point" into the wiki. But then he abandoned the project before completing this after thought. If the wiki were being used and anyone interested in contributing to it, someone would have finished what he started.

--- End quote ---
No
The table of contents is part of the wiki, a dynamic document so by definition it is never going to be complete. Yes it was started by cwdean but it is editable like any other wiki page so we could continue to improve it.

My point was it is already a better point to take users to who select the wiki tab in this forum or in PVD. Neither of which I can change.
The current home page is OK for those coming to the wiki from the internet as then introducing the project is more relevant.

rick.ca:

--- Quote from: patch on September 01, 2010, 12:40:51 pm ---Only moderators and the thread creator can maintain the opening post.
--- End quote ---

If you're going to participate in a discussion, common courtesy suggests you should read what others have posted. I shouldn't have to respond to your misinformation by quoting myself...


--- Quote ---It's also not going to work if there's even the expectation I (or someone like me) is going to maintain it. Restricting the ability to modify posts to moderators is a necessary evil. That doesn't mean there can be only one moderator. Moderators are designated by forum. For this help forum, I would suggest any experienced user should be made a moderator simply by asking.
--- End quote ---


--- Quote from: patch on September 01, 2010, 12:40:51 pm ---The table of contents is part of the wiki, a dynamic document so by definition it is never going to be complete. Yes it was started by cwdean but it is editable like any other wiki page so we could continue to improve it.
--- End quote ---

Uh-oh. You're not even reading what your quoting... ::)


--- Quote ---If the wiki were being used and anyone interested in contributing to it, someone would have finished what he started.
--- End quote ---

You're one of the very few making any contributions to the wiki. But that's only a few additions and a few edits in the last year. Even if a number of users were contributing at the same level, it would be nowhere near "up-to-date." And even if it were, it's not getting the traffic. If you're so convinced a wiki is the answer, post your ideas for reviving it to this topic. Without some damn good ones, we have to conclude the wiki is not viable.

rick.ca:
I just discovered there's a SMF theme that facilitates (sort of) the kind of "Help" forum I'm suggesting...


--- Quote from: rick.ca on September 06, 2010, 09:30:09 pm ---A better solution would be wiki functionality fully integrated with the forum software. That is possible using the WikiStyle SMF theme—which is illustrated rather effectively by the SMF Online Manual. I suppose this would be little more than a polished version of the "Help" forum I suggested—"...topics are 'documents' and replies are 'comments'." The ability to sort topics means they can be presented in any form of TOC, and it seems this should be much easier to do than it is with TikiWiki. You'll also recognize integrating such help documentation with the program is as simple as linking the topic URL's via an HTML help file.

--- End quote ---

I'm not sure how themes work, but I suppose one theme applies to the entire site. If so, that means the help documentation would have to be quite separate from the rest of the forums. For example, the SMF "Online Manual" is at http://docs.simplemachines.org/ while the forums are at http://www.simplemachines.org/community/index.php. If this is the only way it can work, the result would be far from the "full integration" desired. Allowing the same logon for both sites might be feasible, but would require a further mod. It would also not allow posts to be moved to and from the existing forums.

Are my assumptions correct? [Edit:] Fortunately, not. See following posts.

If so, is it possible to make any of these kind of changes to just one forum, rather than all? If not, I still believe what I've suggested is perfectly feasible. I can't imagine why anyone would not understand the first post in a topic is the "help document," and replies are "comments." Nor do I see any disadvantage to the "comments" becoming a discussion.

rick.ca:

--- Quote ---Are my assumptions correct?
--- End quote ---

Apparently not. According to the SMF Manual, themes can be applied at the board level. See (Modify...) "Board Theme" here. So the WikiStyle theme may give us exactly what's needed.

Nostra, can you confirm this?

Navigation

[0] Message Index

[#] Next page

[*] Previous page