Submission Summary: 0 pending, 20 declined, 6 accepted (26 total, 23.08% accepted)
Submission + - Which Android phone from which phone company? (slashdot.org)
frisket writes: "My current phone contract is about to run out, and I'm due a phone upgrade. My HTC Hero has been fine except for the notorious lack of Android proxy support for wireless connections, so I want a new Android phone which provides this. None of the phone companies hereabouts (Ireland) seems to know anything about this, and the forums offer conflicting advice. Is it true that wifi proxy support is disabled to force users to use their phone company's IP connection? What choices do I have (if any)?"
Submission + - Review of JIRA 4 Essentials (packtpub.com)
frisket writes: "The JIRA issue-tracking system has been around for seven years and has proved popular in commercial as well as open-source environments owing to its licensing arrangements (free of charge to certain classes of organizations, and source code available to developers). The release of v.4 in 2009 (now at 4.4) brought some major changes to the UI and searching, a new plugin architecture, and the ability to share project dashboards outside the system. Patrick Li's JIRA 4 Essentials is a comprehensive guide to the interface and facilities that both presents the material straighforwardly and avoids the trap of just being a guide to the menus. Although it is aimed mainly at the administrator, it will also be useful for the desktop user wanting a standalone system.
JIRA is an tracking system for issues arising in software project management and development (the vendor, Australian software company Atlassian, seems to avoid the use of the phrase "bug-tracker".) It's written in Java and runs on all three main platforms, and can be downloaded for server or desktop, or run hosted, and there is a 30-day trial period.
Pricing is scaled by number of users in bands, and is for a perpetual license with a year's support. Although it is commercial software, Atlassian provides it free of charge to open source projects — one reason for its popularity in the movement — and a limited set of non-profit organization types. Academic and developer licenses are also available at a reduced rate.
JIRA 4 Essentials: Track bugs, issues, and manage your software development projects with JIRA is aimed at the administrator who needs a comprehensive description, explanation, and reference to JIRA that goes beyond the online documentation. Patrick Li has also provided a book that the end user can use and learn from (I administer systems, but not JIRA; but I use it for several applications).
So why this book? JIRA's online documentation is very good, and fine for reference and searching, but the book explains the features in much more detail, with more background on factors like why you might want to use one particular feature rather than another. Patrick Li has done what few authors of the "About..." style of book do: produce a readable yet detailed explanation of how to use an application, without simply reproducing each menu in turn.
The book is divided into ten chapters, approaching the topic from the project management and issue management point of view. This approach means that newcomers learns why they might want to do something rather than just how.
Chapter 1 covers getting started: a description of the JIRA architecture (I did say this was for admins and developers), followed by installation options and the installation process itself (Java, MySQL, and JIRA). The examples and screenshots here are for Microsoft Windows users of the standalone version (which comes bundled with Tomcat): experienced admins on Unix-based systems are assumed to know how to install Tomcat and deploy an application. Very sensibly it includes a section on installing HTTPS, something neglected by many web-based systems.
Chapters 2 and 3 are on project management and issue management as dealt with in JIRA. They take an outward-in approach, describing the overall management facilities (project administration and configuration) before going on to the finer detail of components, issues, priorities, and resolutions. This can be a little frustrating for the admin taking over a running system, and needing to perform individual tasks; or for the user wanting to add an issue rather than configure an entire project, but the four-level table of contents provides enough overview to let you find the right section. The running example used for illustration is a project support desk, and the many screenshots are detailed and accurate. Chapter 3 ("Issue Management") in particular is very detailed: this is one area where most users will spend most of their time, so it merits this approach.
Chapters 4 and 5 deal with field and screen management respectively. The fields available in any interface are always an annoyance to the end user: the one you need is never there, and there are dozens that you can't imaging ever wanting. Getting the fields and their configuration right is critical to the success of any installation, and Li rightly spends a lot of the chapter on customising the field set. A similar approach pays off in Chapter 5 on screen management, although it would have been useful to cover some of the concepts of usability such as field order logic, data entry types, and flow logic between screens, which tend to be neglected by busy admins, only to raise issues later with the interface to the issue management software itself.
Chapter 6 is on workflows and business processes: how to adapt the concepts of Chapters 4 and 5 to the business logic of your organization. This is possibly one of the most important configurations, as it forms the interface with the rest of the company, but it is the only chapter I would take issue with, as the writing seems to be less coherent and convincing than elsewhere, as if it was done in haste. It's perfectly accurate, so far as I can tell, and the screenshots are carefully detailed; it's just slightly less easy to read, particularly the central part on transitions and conditions. But this is a small defect overall.
Chapter 7 is on setting up email notification and SMTP. As with most collaborative systems, email can be used both as an input and an output, and there is a set of templates that can be edited to reflect the way your company wants users to be notified. (I live in hope that some company will say "Thanks for submitting ticket XYZ. I'm sorry we screwed up on that one: we're fixing it and we'll let you know." which would be much more honest than the usual marketing claptrap.) Mail submission is an often-neglected way of communicating, and it's good to see it get decent attention.
I mentioned earlier that it was good to see HTTPS being covered: the same is true of Chapter 8 ("Securing your JIRA") which covers the benefits and shortfalls of signup, captchas, the permission hierarchy, and the roles of JIRA sysadmin and JIRA admin.
The final two chapters cover searching and general administration. Searching is one of the biggest bugbears in bug^H^H^Hissue submission: people have so many different ways of expressing what they feel to be the matter that no amount of urging will make them write the same topic when they submit the same bug. Dev teams have to deal with repeated duplicate submissions which would be avoided if search engines would only let people find earlier reports of the same thing, but this magic continues to elude us. JIRA introduced JQL in an attempt to help: this is based on a field=value query syntax which is fine for token list fields, but not much use for freetext searches, where a thesaurus would be more useful. However, Li explains the problem and the solutions available, and also covers setting up stored filters, and creating dashboards and reports. The last chapter (10) deals with customising the general look and feel, colors, logos, date and time configs, and the use of plugins (the Google Docs Connector is illustrated).
Each chapter has a summary, but they are rather short. It would be more useful to see a whole page summarising the material covered, rather than just a few lines: this would then provide a valuable resource when using the book for training. Perhaps a re-issue of the book for v.5 could address this.
There are some minor cultural/linguistic problems with the use of "a software" and "softwares" as nouns, and the occasional appearance of "manual" for "manually", which indicates that some tighter copy-editing might be appropriate for a future edition. There is a good two-level index, but it is unclear from simple capitalisation what the semantics of entries are (a reserved word or phrase? a key value? a prompt or GUI widget?). A minor annoyance is the otherwise very good Table of Contents, which appears to have been done by a Powerpoint user, with the font-size continually shrinking and the margin indenting as the depth increases (for the page numbers as well as the entries!): better control of the design is needed.
Overall, I found the book both readable and useful. It is well illustrated with very clear screenshots, using tooltip-yellow callouts to explain fields and prompts. The writing style is light and illustrative, explaining why an action is needed before how to do it.
On the subject of training, the book would probably be useful to trainers for the same of its detailed procedures (go here, click this, type that, click there). Li does state that JIRA can be used for managing issues outside the software issue-tracking field, which implies that it could be used by non-IT people at some stage, and training would certainly be needed. The HelpDesk application example, which recurs throughout, will probably be a useful point of reference for the majority of readers. If the future plans for JIRA are to extend its reach outside the IT issue-tracking field, it might be useful to develop a non-IT application example for another edition."
JIRA is an tracking system for issues arising in software project management and development (the vendor, Australian software company Atlassian, seems to avoid the use of the phrase "bug-tracker".) It's written in Java and runs on all three main platforms, and can be downloaded for server or desktop, or run hosted, and there is a 30-day trial period.
Pricing is scaled by number of users in bands, and is for a perpetual license with a year's support. Although it is commercial software, Atlassian provides it free of charge to open source projects — one reason for its popularity in the movement — and a limited set of non-profit organization types. Academic and developer licenses are also available at a reduced rate.
JIRA 4 Essentials: Track bugs, issues, and manage your software development projects with JIRA is aimed at the administrator who needs a comprehensive description, explanation, and reference to JIRA that goes beyond the online documentation. Patrick Li has also provided a book that the end user can use and learn from (I administer systems, but not JIRA; but I use it for several applications).
So why this book? JIRA's online documentation is very good, and fine for reference and searching, but the book explains the features in much more detail, with more background on factors like why you might want to use one particular feature rather than another. Patrick Li has done what few authors of the "About..." style of book do: produce a readable yet detailed explanation of how to use an application, without simply reproducing each menu in turn.
The book is divided into ten chapters, approaching the topic from the project management and issue management point of view. This approach means that newcomers learns why they might want to do something rather than just how.
Chapter 1 covers getting started: a description of the JIRA architecture (I did say this was for admins and developers), followed by installation options and the installation process itself (Java, MySQL, and JIRA). The examples and screenshots here are for Microsoft Windows users of the standalone version (which comes bundled with Tomcat): experienced admins on Unix-based systems are assumed to know how to install Tomcat and deploy an application. Very sensibly it includes a section on installing HTTPS, something neglected by many web-based systems.
Chapters 2 and 3 are on project management and issue management as dealt with in JIRA. They take an outward-in approach, describing the overall management facilities (project administration and configuration) before going on to the finer detail of components, issues, priorities, and resolutions. This can be a little frustrating for the admin taking over a running system, and needing to perform individual tasks; or for the user wanting to add an issue rather than configure an entire project, but the four-level table of contents provides enough overview to let you find the right section. The running example used for illustration is a project support desk, and the many screenshots are detailed and accurate. Chapter 3 ("Issue Management") in particular is very detailed: this is one area where most users will spend most of their time, so it merits this approach.
Chapters 4 and 5 deal with field and screen management respectively. The fields available in any interface are always an annoyance to the end user: the one you need is never there, and there are dozens that you can't imaging ever wanting. Getting the fields and their configuration right is critical to the success of any installation, and Li rightly spends a lot of the chapter on customising the field set. A similar approach pays off in Chapter 5 on screen management, although it would have been useful to cover some of the concepts of usability such as field order logic, data entry types, and flow logic between screens, which tend to be neglected by busy admins, only to raise issues later with the interface to the issue management software itself.
Chapter 6 is on workflows and business processes: how to adapt the concepts of Chapters 4 and 5 to the business logic of your organization. This is possibly one of the most important configurations, as it forms the interface with the rest of the company, but it is the only chapter I would take issue with, as the writing seems to be less coherent and convincing than elsewhere, as if it was done in haste. It's perfectly accurate, so far as I can tell, and the screenshots are carefully detailed; it's just slightly less easy to read, particularly the central part on transitions and conditions. But this is a small defect overall.
Chapter 7 is on setting up email notification and SMTP. As with most collaborative systems, email can be used both as an input and an output, and there is a set of templates that can be edited to reflect the way your company wants users to be notified. (I live in hope that some company will say "Thanks for submitting ticket XYZ. I'm sorry we screwed up on that one: we're fixing it and we'll let you know." which would be much more honest than the usual marketing claptrap.) Mail submission is an often-neglected way of communicating, and it's good to see it get decent attention.
I mentioned earlier that it was good to see HTTPS being covered: the same is true of Chapter 8 ("Securing your JIRA") which covers the benefits and shortfalls of signup, captchas, the permission hierarchy, and the roles of JIRA sysadmin and JIRA admin.
The final two chapters cover searching and general administration. Searching is one of the biggest bugbears in bug^H^H^Hissue submission: people have so many different ways of expressing what they feel to be the matter that no amount of urging will make them write the same topic when they submit the same bug. Dev teams have to deal with repeated duplicate submissions which would be avoided if search engines would only let people find earlier reports of the same thing, but this magic continues to elude us. JIRA introduced JQL in an attempt to help: this is based on a field=value query syntax which is fine for token list fields, but not much use for freetext searches, where a thesaurus would be more useful. However, Li explains the problem and the solutions available, and also covers setting up stored filters, and creating dashboards and reports. The last chapter (10) deals with customising the general look and feel, colors, logos, date and time configs, and the use of plugins (the Google Docs Connector is illustrated).
Each chapter has a summary, but they are rather short. It would be more useful to see a whole page summarising the material covered, rather than just a few lines: this would then provide a valuable resource when using the book for training. Perhaps a re-issue of the book for v.5 could address this.
There are some minor cultural/linguistic problems with the use of "a software" and "softwares" as nouns, and the occasional appearance of "manual" for "manually", which indicates that some tighter copy-editing might be appropriate for a future edition. There is a good two-level index, but it is unclear from simple capitalisation what the semantics of entries are (a reserved word or phrase? a key value? a prompt or GUI widget?). A minor annoyance is the otherwise very good Table of Contents, which appears to have been done by a Powerpoint user, with the font-size continually shrinking and the margin indenting as the depth increases (for the page numbers as well as the entries!): better control of the design is needed.
Overall, I found the book both readable and useful. It is well illustrated with very clear screenshots, using tooltip-yellow callouts to explain fields and prompts. The writing style is light and illustrative, explaining why an action is needed before how to do it.
On the subject of training, the book would probably be useful to trainers for the same of its detailed procedures (go here, click this, type that, click there). Li does state that JIRA can be used for managing issues outside the software issue-tracking field, which implies that it could be used by non-IT people at some stage, and training would certainly be needed. The HelpDesk application example, which recurs throughout, will probably be a useful point of reference for the majority of readers. If the future plans for JIRA are to extend its reach outside the IT issue-tracking field, it might be useful to develop a non-IT application example for another edition."
Submission + - Book Review: DocBook 5 (Norman Walsh: O'Reilly) (docbook.org)
frisket writes: "DocBook 5: The Definitive Guide
by Norman Walsh
Edited by Richard Hamilton
ISBN: 9780596805029
Published by O'Reilly in conjunction with XML Press.
Definitive guides by the authors or maintainers of software systems tend to have the edge over other documentation because of the insight they provide. DocBook 5 — The Definitive Guide comes well up to scratch. DocBook has long been the de facto standard for computer system documentation in XML (and SGML before that), and Norm Walsh has revised and updated both the language and the documentation in a concise and valuable form, usable both by beginners and by tech doc experts.
DocBook is a rich XML vocabulary, primarily for the documentation of software systems. It provides markup both for the structure of your documents and for the descriptive detail of your writing, to an extent that few other XML systems match. Like XML itself, DocBook's popularity rests on its robustness, scope, and extensibility; and Walsh makes it clear that the Technical Committee has tried hard to balance stability and adaptability in releasing a new major version which does have a few backward-incompatible changes.
This is a reference book, so the initial chapters (1-5) are short (70 pages) but full of clear explanations of how DocBook works, what it does, and how to use it. Part II is 400 pages, covering every element type in the language, with a detailed description of what it is for, how and where to use it, and how it interacts with everything else. Both for the beginner and the expert, these descriptions are the key to effective use, and Walsh's explanations are clear and comprehensive.
For those of you who have been using DocBook in earlier incarnations, the changes are not deal-breakers, and many of them are welcome rationalizations of the way things have grown organically over the years. It still walks like a duck and quacks like a duck (and the book still has a duck on the cover), so it immediately feels like the same format that you're used to — the changes to element types are relatively few. Chapter 1 (Getting Started) has a brief history, a summary of the changes, and an explanation of the namespace and availability.
If you've never used DocBook before, its structure will still be familiar: in Chapter 2 (Creating DocBook Documents) Walsh explains the division of reference material like books, articles, and manuals into chapters, sections, and subsections, with all the conventional features like lists, figures, tables, and references, as well as the technically-oriented features like equations, programming constructs, interface descriptions, and code samples.
There is help in Chapter 3 (Validation) for those who construct or generate DocBook documents without the use of an XML editor (or even with them: more on editors below). The most common problems with misplaced markup (and the error messages they create) are clearly explained with examples.
Chapter 4 (Publishing) very briefly explains the role of stylesheets (CSS, XSL, and XQuery) in displaying and transforming your documents to other formats, but as these all have their own books and manuals, this book doesn't go into them in any detail.
Customizing DocBook is fairly commonplace, either to avoid the need to commit tag abuse, or to extend its structure into other fields (I added a new element type for typographical examples for my book on LaTeX, and it only took a few minutes). Chapter 5 provides some rules and explanation of customization layers and modularity for those who design schemas and DTDs.
The five Appendixes cover Installation, Variants, Resources, Interchange, and the GNU Free Documentation License — yes, you can read the whole thing online at docbook.org, for which Tim, Norm, and many others are to be thanked. It is a rare publisher who groks the need to be able to point someone at a reference, or quote it in email or a tweet, where a paper copy doesn't cut the mustard.
There isn't anything here about actually using an XML editor or about how to choose one. Editors do of course all come with their own documentation (much of it written using DocBook) and editor selection can be a complex business. However, there is a list of some common tools in Appendix C (Resources). Editors are a minefield, as my own research into the usability of editing software for structured documents is showing, so I can understand the omission, but some pointers to editor resources would have been useful.
The chapter on Publishing is useful for those who haven't been in the publication process before, but it could have emphasized more the need for accuracy and consistency. Experienced technical authors know this, but many other writers don't see the need for it, assuming that the publisher (or some elf) will automagically heal everything before publication. DocBook 5 and this book will help enormously, but author-edited documents sometimes unwittingly misuse or abuse the markup, no matter how exhaustive the manuals.
If you write computer documentation, or anything related to it, from a conference paper to a thesis to a book, DocBook 5 is probably what you should use if you want the document to survive and to be usable and reusable; and this is the book to help you do it."
by Norman Walsh
Edited by Richard Hamilton
ISBN: 9780596805029
Published by O'Reilly in conjunction with XML Press.
Definitive guides by the authors or maintainers of software systems tend to have the edge over other documentation because of the insight they provide. DocBook 5 — The Definitive Guide comes well up to scratch. DocBook has long been the de facto standard for computer system documentation in XML (and SGML before that), and Norm Walsh has revised and updated both the language and the documentation in a concise and valuable form, usable both by beginners and by tech doc experts.
DocBook is a rich XML vocabulary, primarily for the documentation of software systems. It provides markup both for the structure of your documents and for the descriptive detail of your writing, to an extent that few other XML systems match. Like XML itself, DocBook's popularity rests on its robustness, scope, and extensibility; and Walsh makes it clear that the Technical Committee has tried hard to balance stability and adaptability in releasing a new major version which does have a few backward-incompatible changes.
This is a reference book, so the initial chapters (1-5) are short (70 pages) but full of clear explanations of how DocBook works, what it does, and how to use it. Part II is 400 pages, covering every element type in the language, with a detailed description of what it is for, how and where to use it, and how it interacts with everything else. Both for the beginner and the expert, these descriptions are the key to effective use, and Walsh's explanations are clear and comprehensive.
For those of you who have been using DocBook in earlier incarnations, the changes are not deal-breakers, and many of them are welcome rationalizations of the way things have grown organically over the years. It still walks like a duck and quacks like a duck (and the book still has a duck on the cover), so it immediately feels like the same format that you're used to — the changes to element types are relatively few. Chapter 1 (Getting Started) has a brief history, a summary of the changes, and an explanation of the namespace and availability.
If you've never used DocBook before, its structure will still be familiar: in Chapter 2 (Creating DocBook Documents) Walsh explains the division of reference material like books, articles, and manuals into chapters, sections, and subsections, with all the conventional features like lists, figures, tables, and references, as well as the technically-oriented features like equations, programming constructs, interface descriptions, and code samples.
There is help in Chapter 3 (Validation) for those who construct or generate DocBook documents without the use of an XML editor (or even with them: more on editors below). The most common problems with misplaced markup (and the error messages they create) are clearly explained with examples.
Chapter 4 (Publishing) very briefly explains the role of stylesheets (CSS, XSL, and XQuery) in displaying and transforming your documents to other formats, but as these all have their own books and manuals, this book doesn't go into them in any detail.
Customizing DocBook is fairly commonplace, either to avoid the need to commit tag abuse, or to extend its structure into other fields (I added a new element type for typographical examples for my book on LaTeX, and it only took a few minutes). Chapter 5 provides some rules and explanation of customization layers and modularity for those who design schemas and DTDs.
The five Appendixes cover Installation, Variants, Resources, Interchange, and the GNU Free Documentation License — yes, you can read the whole thing online at docbook.org, for which Tim, Norm, and many others are to be thanked. It is a rare publisher who groks the need to be able to point someone at a reference, or quote it in email or a tweet, where a paper copy doesn't cut the mustard.
There isn't anything here about actually using an XML editor or about how to choose one. Editors do of course all come with their own documentation (much of it written using DocBook) and editor selection can be a complex business. However, there is a list of some common tools in Appendix C (Resources). Editors are a minefield, as my own research into the usability of editing software for structured documents is showing, so I can understand the omission, but some pointers to editor resources would have been useful.
The chapter on Publishing is useful for those who haven't been in the publication process before, but it could have emphasized more the need for accuracy and consistency. Experienced technical authors know this, but many other writers don't see the need for it, assuming that the publisher (or some elf) will automagically heal everything before publication. DocBook 5 and this book will help enormously, but author-edited documents sometimes unwittingly misuse or abuse the markup, no matter how exhaustive the manuals.
If you write computer documentation, or anything related to it, from a conference paper to a thesis to a book, DocBook 5 is probably what you should use if you want the document to survive and to be usable and reusable; and this is the book to help you do it."
Slashdot Top Deals
Kleeneness is next to Godelness.
