| Info | Message |
|---|---|
| 21) Message boards : Documentation : Content Planning & Information Architecture
Message 10875 Posted 12 Jun 2007 by Lee Carre |
Man, I miss the feature on Pirates where it jumps to the end of a thread you've already read. I'll have to get those patches to Rytis. :-)That was quite a handy one, but seemed to be implementation specific, and very sensitive to changes in the code when a project customised things. It's JavaScript dependant isn't it? That'll have to be changed to use a better - at least; more accessible - method. You Can't Rely on JavaScript Being Available. Period. Why aren't the patches in the CVS anyway? |
| 22) Message boards : Documentation : Content Planning & Information Architecture
Message 10874 Posted 12 Jun 2007 by Lee Carre |
Eric Myer wrote:Lee Carre wrote:Ah, excellent. The next problem is how users are going to get there, or even find it?Trac is open to anybody, though you do now need to register. So we can work on improving the Trac wiki documentation. That may be best thought of as the Reference Manual.I'm actually warming to your way of thinking now. If it's a reference then it doesn't need to be publicly advertised, and knowledge of it's existance will spread via word of mouth in the formus (I assume?) I would expect that they would only be interested in hosting something else at Berkeley if it was already in good shape and easy to maintain. There was some talk at one point about Berkeley hosting what is now the UBW, but they didn't want it in the form it was in, and that may in fact be when "Unofficial" was added to the name.Well, that's that's a bit cheeky considering the official boinc site leaves a lot to be desired, and something is better than nothing. But I see their point. So I think it's better to try to construct something useful, and not worry about where it might be hosted. That can change, as appropriate.I've always said high-quality content is essential. But as for having the main (and rather important) user guide elsewhere won't be that bad as long as users can find it easilly, and it's well known about; by that i mean having prominent links from boinc.berkeley.edu and similar so users can jump straight to the guides once they've downloaded the installer. I agree that hosting can change, and is somewhat irrelevent (as long as it's good & stable, and the URLs won't be changing; they do matter). In the meantime where can we host our rough version while we're tweaking it? I could host it on my own server at home, but it can't sustain high-traffic, it would be for demo purposes only, as a mock-up of the navigation for example. I suppose no option is ideal, because it's hard to avoid a single point of failure (eg, the admin with control). Who do we need to contact about this? Dave Anderson, Rom?Yes, and they might even read this section, but I would rather not bother them with details and instead try to come up with a good overall plan and present it to them for comment. They have lots to do, let's not take up their time until it's really necessary.[/quote]Agree. So as a seperate project, how are we going to go about hosting it? I'm not saying we should jump into hosting right now (quite the opposite, the plan needs to be done first), but i'm just thinking ahead; I find it helps avoid issues down the line if you can see problems coming :) Of course they are always welcome to jump in to this disucssion if they wish, or to just read but not comment.I assume they all know it exists considering it was one of them who created this froum section. |
| 23) Message boards : Documentation : Inventory
Message 10873 Posted 12 Jun 2007 by Lee Carre |
Eric Myers wrote:Lee Carre wrote:very good point lolI didn't realise that it's a vast resource LOL Eric Myers wrote: Lee Carre wrote:Oh well, done now, and i'll leave it as it so it's a proper list of the resourcesI've updated my original post with the new URLsNo need for that. This is just a discussion and we will take what we get from it and compose it into a more refined product elsewhere. Eric Myers wrote: What is the re-editing timeout on this board?I believe it's an hour by default. Although I have issue with the idea of being able to edit for an hour, then not at all, not even to correct spelling/grammar errors, seems very counter-productive on the usability front lol |
| 24) Message boards : Documentation : Content Planning & Information Architecture
Message 10869 Posted 12 Jun 2007 by Lee Carre |
Eric Myers wrote:The idea here is to discuss and coordinate all the BOINC documentation efforts (or at least those that we can have some influence over).I posted my thoughts on these issues in BOINC FAQs I believe that the user guide should be on the berkeley site, and if it's really got to be on a seperate site; detailed developer info elsewhere (see the linked post for my reasons). Having them both on the same site would be better, under 2 main sections ("guide" and "reference"). This all depends on the ability to make the berkeley site into something decent, otherwise it's useless. Considering that, before we start planning around the idea of using the berkeley site, lets establish that it can be used as intended so we don't waste time having to re-plan. Who do we need to contact about this? Dave Anderson, Rom? |
| 25) Message boards : Documentation : Inventory
Message 10867 Posted 12 Jun 2007 by Lee Carre |
Eric Myers wrote:Lee Carre wrote:fragmentation is an example of what all too easilly happens without good information architecture design and maintainence :pThe Spy Hill BOINC related help pages. That page itself is not a good entry page for guiding people to what they may be seeking, though it tries to make it clear that it is for application developers and project managers and to steer volunteers just running the client elsewhere. And those pages in general are not as well organized as they could be. They've just grown to be the way they are over time. Eric Myers wrote: Lee Carre wrote:I was just going by the link text, I assumed you wanted the main TWiki page, but i suppose i should have checked if it was appropriate. I didn't realise that it's a vast resource LOLThat is the top level of the CERN wiki, and it gives you an idea of what a Twiki wiki looks like. It can be divided into various "webs" for different projects. Those are all listed in the left hand nav column. I find this confusing and unhelpful. Somewhere in that mess there are some useful pages about BOINC from the folks who created LHC@Home, but searching for BOINC doesn't find them. I've updated my original post with the new URLs |
| 26) Message boards : Documentation : Content Planning & Information Architecture
Message 10864 Posted 12 Jun 2007 by Lee Carre |
For planning & discussion of purpose, goals, and content requirements I think the general purpose/goals are established in other threads. As for content, we need a good idea of all the things we'd like to have (eg, collecting ideas then filtering them). Once the desired content is established, then it can be formed into a hierarical structure. the most obvious for the user guide are installation walkthroughs and links to errors/problems which might occour during the process with ways to fix any issues that come up. probably best to have it as a side-article, but some discussion on the pros/cons of each type of installation, so users can make a more informed choice which better fits their needs. for the reference, things like the actual spec of the app_info.xml file ideally details on how things work (such as how the schedulers make decisions described in plain english (with the maths equations as a technical suppliment) |
| 27) Message boards : Documentation : BOINC FAQs
Message 10863 Posted 12 Jun 2007 by Lee Carre |
Trog Dog wrote:Eric Myers wrote:Again, i strongly recommend that a more distinctive name be given to what's currently called "F&Q" - it's too similar to FAQ (which most people are already familiar with) and "F&Q" isn't very descriptive, it gives no indication of what "F" and "Q" mean in this context....(And that still leaves room for the FAQ or F&Q as well).Wouldn't the FAQs then become part of or linked from the Users Guide - and the F&Qs (the not so frequently asked but still handy to have :) ) part of the Reference Manual. How about "common problems" ? It depends on it's purpose. If "Facts & Questions" is what people really want (regardless of usability) then use the full name for the actual page/document so it's more distinctive. The problem with "Facts & Questions" is that if it contains questions, how are they different to "Frequently Asked Questions" ? If the answers to the questions are valuable as people say, then why not write some proper articles to address them? |
| 28) Message boards : Documentation : BOINC FAQs
Message 10862 Posted 12 Jun 2007 by Lee Carre |
mo.v wrote:Sounds logical, Eric. It would require a lot of moving stuff round, writing and rewriting.So would any overhaul mo.v wrote: I'll take a case in point - a CPDN reference + fix document I recently helped to write about the 'Max CPU time exceeded' error, which has also occurred on other projects.lots of (appropriate) interlinking will be needed to tie related things together. |
| 29) Message boards : Documentation : BOINC FAQs
Message 10861 Posted 12 Jun 2007 by Lee Carre |
Eric Myers wrote:Trog Dog wrote:Agree, excellent idea. One as a guide and one as a "find the specific thing you're looking for" type resource.F&Q :)That or "Users' Guide". This is part of one of the arguments for having at least two separate sites for documentation. I vote for "user guide" rather than "user manual" to make the point that it's designed to be a tutorial style thing rather than just odd How-To's Eric Myers wrote: (snipped detailed explanation, which was rather good actually, for breivety)I'm not against the idea of having the BOINC site as the reference manual, but the content of the boinc site would need to be vastly improved with a major overhaul, and use a system which allowed continued maintainence which didn't have to go through Rom (so he's not the bottleneck as it were). Although my main thought is that the roles should be reversed, new users are more likely to want the guide, so that should be on the boinc site and the reference manual (which more experienced users will want) should be on the different/seperate/indepentant site if that's the desired organisation (2 seperate sites). |
| 30) Message boards : Documentation : Inventory
Message 10860 Posted 12 Jun 2007 by Lee Carre |
mo.v wrote:Eric, could you please give us active links to all 5 collections?I assume these are the correct URLs, please update if incorrect. |
| 31) Message boards : Documentation : UBW domain names
Message 10859 Posted 12 Jun 2007 by Lee Carre |
Eric Myers wrote:mo.v wrote:Partly? The wiki system produces a flat navigation system though? Unless I'm missing something here.I think that means always-visible and all-embracing menus and tree structure, which is perhaps what's lacking or only partially-implemented at the moment.Partly implemented, I'd say. And I'll have more to say about that in a bit. Eric Myers wrote: mo.v wrote:Disagree, to design a good architecture/structure, you really have to have a pretty good understanding of the essence of the project. One of the main reasons is that your information architecture (and thus your site structure) shouldn't just be designed for today & now, but allow flexibility (eg, in how you name & organise things) to expand gracefully in future, and by gracefully I mean not having to drasticly change URL structure, or "redesign" the site.This can only be designed by people who, unlike me, understand what boinc consists of in its entirety, and how the different aspects subdivide.I don't think so. I don't think you have to understand all the details to start with the general picture. Eric Myers wrote: If we start at the top (or the base of the tree) then we can break things in to smaller parts, then those into smaller parts. You don't have to know where everything will end up to get started organizing this way. What does help though is to talk it through first and get the general idea layed out.To an extent I agree that people dealing with, or responsible for a particular section don't need to know what's going on in other sections, but it makes a significant difference to the site appearing an a coherent and cohesive whole. When initially designing the basic structure, a good, detailed knowledge of how the site should work, and the essence of the content is needed if the design is to be good, effective, future-proof, usable, and generally high-quality. Eric Myers wrote: On the Trac wiki at Berkeley there are three main links on the first page. The first link is for participants (volunteers, the users who run the client), the second for those who want to create projects or applications, and the third for code developers. I think that's a pretty good start at dividing things up by intended audience. Most people will quickly follow the first link, but knowing the others exist doesn't hurt unless it's confusing.A good point about this style of division was made about the FAQs. Dividing by target audience is the simplest method, but in many ways it's very limiting, you're leaving it up to users to decide on their level of knowledge (eg, basic/beginner or intermediate/advanced - I'm sure you can imagine a user going into a section which doesn't meet their level of experience, such as when a user doesn't consider themselves a "computer person" therefore they must be a novice type thinking, or similar (such as the reverse lol). A generally better way is to divide by subject (or similar, whatever's appropriate) and then the user can decide on an article-by-article/topic-by-topic basis if the content is beyond them. A point about dividing by subject, obviously the content should be as simple as possible (possibly with links to sub-pages with more technical detail to satify the more technical folk) because more knowledgeable people generally don't mind an article which is aimed at less experienced users as long as it still gives the answer(s) they were seeking. So it's quite possible to divide by subject, which is generally more effective - imagine that the answer a user is looking for is in the "advanced" section due to it's complexity, yet their looking in the basic/novice section, but are capable of applying the fix/work-around which could be quite simple in comparison to the problem. Basically it comes down to; how do you decide what experience level something should be categorised at? Considering that something which is easy for people knowledgable about programing, might not be easy for people knowledgable about networking. Or vice-versa. The reverse is also true, what if the answer I'm looking for is actually in the "novice" section, but I'm in the advanced section because that more closely matches my experience level? One solution is to duplicate content between sections divided in this manner, but that brings non-trivial problems of it's own. Again, I'm lead back to recommending that content be divided by subject (or similar). Eric Myers wrote: Then each of those categories needs to be divided up in broad terms. That requires knowledge of those areas, but one person doesn't have to be an expert in all of them. Like distributed computing, we can divide the task at hand an conquer it.The point about knowledge of multiple areas comes back to the issue of making the site a coherent/cohesive (I'm sure my spelling is appauling lol) whole. So that different, but related articles feel like they tie together, and there's no "content gap" which seems to occour often enough for it to be a problem in such an editorial system. Also, how is quality assurance and/or quality control going to be maintained (eg, good content) with different people making random edits to different sections? This is again why having a good overview produces a better structure, because that person is much more aware of how changes to sections for example, affect the site as a whole. |
| 32) Message boards : Documentation : UBW domain names
Message 10858 Posted 12 Jun 2007 by Lee Carre |
mo.v wrote:I think that means always-visible and all-embracing menus and tree structure, which is perhaps what's lacking or only partially-implemented at the moment.Exactly, that's at least one way of going about it, and generally the most commonly used which means it's a good choice because people are most familiar with it. mo.v wrote: This can only be designed by people who, unlike me, understand what boinc consists of in its entirety, and how the different aspects subdivide.Being an area of such critical importance this needs to be planned well on many fronts, my notes on good planning process point out that purpose, goals, scope and content should be established before you can expect to design a good architecture or navigation system. |
| 33) Message boards : Documentation : UBW domain names
Message 10857 Posted 12 Jun 2007 by Lee Carre |
Eric Myers wrote:Keck Komputers wrote:Good navigation is critical to a usable site. It's good that fixing it is desired, but it should also be a "MUST" item on the ToDo list, as a requirement. There's not much point without it.I have been an editor there for a long time, probably since it was created, and I still have trouble navigating to the page I want sometimes.Me too. The overall organization is the biggest problem I'd like to tackle. [quoteEric Myers]One thing we might want to point out is that searching the wiki is different from Google. It first tries to find a page with an exact match to what you entered. That failing, it looks for pages which have a partial match in the title. And then it lists matches in the article body. I think this is actually the right way to search the wiki, but some people seem to have a problem with it just because it is different from Internet search engines. We might look for a way to help make this point visible.[/quote]This is all about how the results page is presented. If it's not clear how the search was performed, then the results will be confusing. The one issue with this method is that it seems to be a workaround to the google approach of trying to return the most relavent results (well, at least google tries to give relavent results), but again, this comes down to information architecture and having a good search system, neither are easy or simple things. Eric Myers wrote: Searching on the Trac site is another thing. Ugh. You don't just get wiki articles, you get the revision log, bug reports, the kitchen sink. Even searching the Berkeley site with Google set to their domain gives message board postings and boinc_dev e-mails. There needs to be a way to easily search *just* the documentation pages.Completely agree, the Trac system feels very fragmented, and that it's trying to be too many things when using seperate systems would do each section better than a general purpose one. Trac is much improved compared to some bug management/tracking systems I've seen, but I agree there's still much room for improvment. Obviously general improvements should be made to the Trac source (eg, applied to the actual project source) rather than the BOINC specific implementation, however I can imagine several BOINC-only improvements being benificial. |
| 34) Message boards : Documentation : UBW domain names
Message 10856 Posted 12 Jun 2007 by Lee Carre |
Eric Myers wrote:mo.v wrote:Considering you can't change users, and even if you could that's the wrong way to go about it; it's usually always the site nav being unusable, or at least hard to use.I have the same problem with the Boinc website. I have the impression that there may be large parts of it that I've never discovered...The problem is not with you... Eric Myers wrote: I think both wiki's need better organization, to help you find what you are looking for (even if you don't quite know) and to give you some confidence that you are able to easily find everything available.Agree entirely with the principal, however the current navigation system is inherent to mediawiki isn't it? So unless the wiki system can be changed (so we can have a proper information architecture with proper URLs) then another CMS is needed instead. That alone won't be an easy thing, that is if we want the output to be good quality, efficient code, accessible etc. However, there are some rather good open source CMS packages out there. |
| 35) Message boards : Documentation : UBW domain names
Message 10855 Posted 12 Jun 2007 by Lee Carre |
Keck Komputers wrote:I like boinc.info for the URL, that should cover any future changes well and get the point across quickly.Agree completely, but if it's taken then a "boinc*.info" domain (* = any) would be the next best thing. This is where the purpose of the site is important, if "boinc documentation" or similar isn't appropriate or desired (as peaple have said is the case with "knowledge base" - but see my comments about KB vs Wiki) then what would be appropriate? Keck Computers wrote: [quot=mo.v]I must admit that although I recognise that there's a vast amount of invaluable information in the Boinc Wiki, I have never learned to navigate it properly or even form a mental image of its structure.I have been an editor there for a long time, probably since it was created, and I still have trouble navigating to the page I want sometimes.[/quote]I think that says it all lol - about the site navigation i mean, and that it must be extremely lacking if a long-term editor has trouble. New visitors really wouldn't stand a chance in that case. |
| 36) Message boards : Documentation : Inventory
Message 10829 Posted 10 Jun 2007 by Lee Carre |
I think it would be useful to take an inventory of what documentation exists "out there" for BOINC, as the first step in:(how do you create an ordered list?) I would suggest the reverse, decide what we want first, so it's not influenced by what we already have. All too often i see "redesigns" which are just modified versions of what's already there because the team didn't start afresh. By all means take anything useful from what already exists, but only after it's been decided what's needed, thinking in ideals ignoring any technical limitations which can be looked at later when it comes to implementation. Given that the work is all done by volunteers, step 3 needs to be evolutionary rather than revolutionary.Agree, so far the "revolutionary" approach has repeatedly failed, with site after site trying to be the "all-new, only resource you'll ever need" type thing. Collaboration is always evolutionary, but I suggest this doesn't mean the creativity and ideas need to just be modifications of the existing state of things. I'd say revolutionise the structure, process (eg editorial process), but evolve how we all go about it. The first issue is where to host the improved resource, and a general idea of how it's going to be done (eg, what technology is it going to be based on?) Or even better, have a high quality site for discussion by all involved, work on content first (content is king) then once that's established decisions about hosting (which should be based on the needs of content) can be looked at. So for starters, we haveI think you've hit on an important point here; the lack of colaboration (for whatever reason). Things are very fragmented at present, yet it's more useful to have a central coherent resource (as long as it's good with high-quality content). Another question is whether (in the long term) there should be only one wiki (presumably at Berkeley) or if there is a reason for having more than one? I can think of good arguments for both.I'd like to hear them, from a usability point of view (again, assuming a good site with high-quality content) a single resource is easier. However, different resources could deal with different subjects/areas; such as one for beginners etc. and one for developers containing more technical information & discussion about development of the software and web side of things (inc. documentation). |
| 37) Message boards : Web interfaces : BIONIC Web page issues
Message 10828 Posted 10 Jun 2007 by Lee Carre |
There are hundreds of minor fixes which need to be made, but in reality the whole front-end needs a major overhaul, however it's being worked on :) And yes, i'm aware of W3C standards (and validation), usability, accessibilty, efficient coding, CSS positioning/layouts instead of tables, semantic markup ((X)HTML) etc. I just need the co-operation of other developers if the final end product is going to be good. I believe the lack of a doctype is due to the fact that the current front-end code is far from any form of valid structure, so at present it's better to have the browser parse pages in quirks mode, rather than standards compliant mode (which is what adding a doctype would cause). encoding issues are complex, as the system is complex and encoding involves everything from data-input, database storage formats, PHP processing between the DB and the front-end, and of course; HTTP and such too. Trust me, these issues have annoyed me for some time, but they're being worked on. If you have any other issues/bugs to report, no matter how minor, please let me know and I'll add them to the ToDo list. |
| 38) Message boards : Documentation : UBW domain names
Message 10827 Posted 10 Jun 2007 by Lee Carre |
Whatever name is chosen, I don't think it would generally be a good idea to have different compilations/collections for different levels of competence. I suggested above that when more than one method or fix is possible, they can be categorised by level of difficulty. But I meant within the same collection so that the choice available is clear.good points, i withdraw my previous comments, and now agree with this idea, but it will only work if done very well, making it very clear who each level is intended for (with explanations beyond the short names; "IT literate" could cover a whole range of skill-levels). The other problem is that many people would think: "'IT litterate', I'm not computer litterate, therefore that doesn't apply to me" sort of thinking, so the wording used to describe each level needs to be carefully thought through, but it's possible to make it effective. Perhaps just base it on difficulty (eg "easy" "intermediate" "advanced" type thing) rather than trying to assume what level of experience would be required. An example of why, being that if a user is experienced but only in one area of IT, that doesn't mean they'll find another area easy too. Eg if they're experienced with using a computer, that doesn't mean they know how to troubleshoot and fix hardware issues. Navigation within the collections is of paramount importance.of course, this cannot be understated I must admit that although I recognise that there's a vast amount of invaluable information in the Boinc Wiki, I have never learned to navigate it properly or even form a mental image of its structure.Agree, it seems that the system tries to remove any form of hierarchy (sp?) to the extent that in wikipedia, custom mini-navigation aides need to be created for related articles (take a look at the various networking articles, especially protocols). I think this idea stems from an odd view of hypertext theory, in that the web is in some ways structureless (you can jump from random location X to random location Y with just one link), but that's only really appropriate between sites. Within the same site, structure, information architecture, hierarchy etc. are all critically important for a sucessful user experience. A simple case being the awareness of where you are in the overall structure, which again, the mediawiki systems seems to avoid, you could be anywhere in the overall structure, unfortunetly i think that's by (poor) design. I have the same problem with the Boinc website. I have the impression that there may be large parts of it that I've never discovered, and that what I do discover is more or less random. Maybe the problem's within me (ie my own random access memory), not within these websites.the boinc site is a classic example of a bunch of pages stuck together without being made to form a coherent, cohesive whole. The same problems apply but for different reasons. Both cases need to be avoided. I wouldn't be surprised if many people didn't use resources like the boinc wiki due to it's lack of structure and poor usability. As I've said before, these issues need to be resolved for it to be useful and effective/secessful in it's goal(s). |
| 39) Message boards : Documentation : BOINC FAQs
Message 10826 Posted 10 Jun 2007 by Lee Carre |
Highly likely to be confused with the original "FAQ" by users. I suggest choosing a more distinct name. The idea is otherwise fine :) |
| 40) Message boards : Documentation : UBW domain names
Message 10814 Posted 9 Jun 2007 by Lee Carre |
Lee wrote:The reason for suggesting this was to avoid depending on dozens of domains (once you publish URLs you can't then render then to produce a HTTP 404 (by removing content)).I strongly advise against using names which specify a particular technology (such as MediaWiki). Something more generic will have a longer life, eg after the MediaWiki system is no longer used lol. I would also suggest choosing the most appropriate name we can think of as early as possible (obviously if a better name is thought of later, then that should be used as time goes on). This avoids "moving" the site from domain to domain, which has odd effects for things like google rankings (I assume we want documentations sites to be as high as possible?) I don't like "Knowledge Base" because that also implies a certain kind of structure (based on how HP and Apple and others do theirs), and usually a more non-collaborative format. I've argued with Jord that the FAQ is really a Knowledge Base because some of those questions are not so frequently asked. Even so, making that information easily available is very important whatever it's called. I'm sure this debate will continue.well, it doesn't have to be "KB" obviously something more appropriate and descriptive, my point was don't include "wiki" because most user's don't know the term, it doesn't describe what the site is about, and is technology specific; the name should describe the purpose. The nice thing about using "wiki" in the name is that it suggests the collaborative nature of the thing, based on the model of Wikipedia, which I don't think is going to disappear anytime soon.To those who know what a wiki is, yes. But how many average users will make that connection? Surely a descriptive name will serve the purpose better, and remove various questions/doubt? I have a similar naming problem on the I2U2 project. On both the mock-up site I've set up for I2U2 and on Pirates@Home I call the attached wiki the "glossary", but the content is actually much more than a collection of definitions of words (though it has that too) and I would like to find a better name for this which does not use "wiki" in the name. (One practical reason is that there are also other wiki's involved. For BOINC we have the Trac wiki, while for I2U2 my collaborators and I are doing some of our development using a Twiki based wiki.)In a way this shows exactly my point, if you base a name on technology, your 3 options are;
|
Copyright © 2025 University of California.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License,
Version 1.2 or any later version published by the Free Software Foundation.