I have appreciated all the discussion on Mark's excellent post. It's not the first time we've had this discussion, but it seems the last overhaul of the documentation met some needs, so it has been awhile. In other words, I think we have made some progress with the documentation, but we are not there yet. Here's few responses to various points raised by different individuals:
Mark: For example, I still do not know the difference between "handbook", "documentation" and "help system". The documentation is the complete set of doc pages on the BoltWire site. If you look at the first column here http://www.boltwire.com/index.php?p=docs you will notice the Handbook is one subset of the doc pages. The Handbook is designed to be a master list of all the commands, conditionals, functions, markups and variables in BoltWire. The five main building blocks. Kind of a master list of the stuff BoltWire understands. All the other pages deal with everything else. The Help system is a built in, dynamically generated function in BoltWire that can be handy when trying to figure out how something works. It is mostly helpful for those who know php. To study the various time functions for example, just add &help=time to the url and right in your current page help information drawn directly from the source code is visible. I don't recall if it's turned on or off by default. But you can try it on the BoltWire site easily enough. I like it because I can see the actual code and decipher what the syntax is supposed to be, etc. I rarely look at the docs--I go straight to the code. It is also a shortcut of markups when the user is not logged in. Mark: BoltWire is used for blogs, forums, wikis, PIM, websites, webshops, etc.. I think all these specific wishes would best be served by making tutorials for each. Agreed, this has been our real need. The problem is, who is going to write them. I'm afraid I don't have the time. It would be nice if those who develop some specific BoltWire application to document how they did it for the benefit of others. But it's time consuming process. So the docs can only grow in this area as we have contributors. The other docs grow by adding a piece here and there as some question is answered on the mailing list. But these tutorials take a raw investment to get the initial page off the ground. Personally I prefer editing to writing... Mark: I think the documentation would be best if it is split up into the different aspects of boltwire. I would make the following categories: If you look again at the main docs page (the left column) you will see we already have some of these sections. Including an "administration", "handbook", "extending BoltWire", "layout", and a "start" section (not showing) corresponding to some of your suggested categories. I'm open to making changes to the outline, but I would rather tweak what we have than try and start over again from scratch. Suggest one or two specific changes you'ld like to see to start with? And then we can go from there... Markus: For Dan it is almost by definition extremely challenging to write documentation exactly the way a new user needs it This is more of a problem because I almost never use the documentation. If I can't remember how to do something, I just open the source code and take a quick peak. I find it quicker and easier to get information that way. So I almost never even look at the documentation. Really, there's no way I can keep up with that. But the problem is bigger. Even new users are going to expect the docs to be different depending on their background and what they are used to. We all have different ways of thinking, different backgrounds, are use to different software prior to using BoltWire, so any way we set up the documentation will make it easier for some and harder for others. Mark has good suggestions, but I don't think it's that far off from what we have. If you use the hierarchical list. I personally find the alphabetical list more useful (the right column). And others just use the search feature. So we want to give users several options, and keep the organization at least reasonably logical. Part of learning a piece of software is just learning how the documentation works. Linly: Btw, Dan has mentioned a "rating/flagging system" for the docs here: I'm open to it. It's another option. But there hasn't been too much demand, and I'm not sure how it would work for the docs. I think it might be more useful for the solutions. At least rating and tagging. For the docs, some kind of flagging system would be nice, where questions could be asked. We could have simple comment boxes, and then keep a list of recent comments so issues could be addressed right there on the site. That would probably work well enough... To set aside time to develop these things I need more urging though. I find myself more enjoying BoltWire these days, and less developing it. Karl: One area that I feel would help the documentation area would be more examples. Yes, the more examples the better! Anyone with a member account is able to add examples. I'm not so keen on popups or subpages, and would probably just as soon weave them into the doc page and put them in a code tag. It makes the pages longer, but it's all there together at your finger tips. Tooltips are ok, if you notice they are there. The bigger problem is getting people to contribute the examples... Almost never using the documentation, I rarely think to copy little snippets to it. We do have the http://www.boltwire.com/index.php?p=solutions.snippets page, but it is woefully underdeveloped, and I don't think people are likely to use it. Still, is it better as solutions or as documentation? Vincent: Just about the time I am giving up BoltWire to keep looking for an "easy and flexible" software of this sort. Glad you are willing to give us a second chance. We have a small community, but a good one, and a growing one. Could you give me an example of two of what you found frustrating in learning BoltWire. Not only can we probably give you some help, but it would help me to identify the blind spots in our documentation. I have not tried everything out there by any means, but I do believe BoltWire is exceptional in a number of ways. After trying Drupal, Moodle, and PmWiki, I find BoltWire far faster, more flexible, and easier to use. It may just be my coding skills have increased, but I think it is the design architecture. If you stick with it, I don't think you will be disappointed. Give us a chance to help you get over the hump... Karl: 1. Beginners section which covers basic setup and configuration. 2. a Reference section which contains categories and Sub categories. I think this is exactly what we have. The start and handbook pages are just two sub sections of the doc area. Is the sidebar confusing? My thinking was having direct shortcuts to the start and handbook sub sections would be helpful. And that most users would eventually start going straight to the docs page for a full list of the topics/structure, and titles. I sense from the confusion here somehow this is not coming across too well. Can someone help me see what I'm missing? Thanks for everyone's input. It's great to see a community that cares enough to contribute to this software's development like this. We've come a long ways--thanks for urging us on to go even further. Cheers, Dan On Wed, May 20, 2009 at 10:07 PM, karlh626 <[email protected]> wrote: > > I was looking at the popup solution and found the tooltip solution. > This might be a better way to show examples. > > > --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "BoltWire" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/boltwire?hl=en -~----------~----~----~----~------~----~------~--~---
