Another Word For It Patrick Durusau on Topic Maps and Semantic Diversity

April 14, 2013

Nozzle R Package

Filed under: Documentation,Graphics,R,Visualization — Patrick Durusau @ 3:29 pm

Nozzle R Package

From the webpage:

Nozzle is an R package for generation of reports in high-throughput data analysis pipelines. Nozzle reports are implemented in HTML, JavaScript, and Cascading Style Sheets (CSS), but developers do not need any knowledge of these technologies to work with Nozzle. Instead they can use a simple R API to design and implement powerful reports with advanced features such as foldable sections, zoomable figures, sortable tables, and supplementary information. Please cite our Bioinformatics paper if you are using Nozzle in your work.

I have only looked at the demo reports but this looks quite handy.

It doesn’t hurt to have extensive documentation to justify a conclusion that took you only moments to reach.

February 15, 2013

“Document Design and Purpose, Not Mechanics”

Filed under: Documentation,Software — Patrick Durusau @ 1:51 pm

“Document Design and Purpose, Not Mechanics” by Stephen Turner.

From the post:

If you ever write code for scientific computing (chances are you do if you’re here), stop what you’re doing and spend 8 minutes reading this open-access paper:

Wilson et al. Best Practices for Scientific Computing. arXiv:1210.0530 (2012). (Direct link to PDF).

The paper makes a number of good points regarding software as a tool just like any other lab equipment: it should be built, validated, and used as carefully as any other physical instrumentation. Yet most scientists who write software are self-taught, and haven’t been properly trained in fundamental software development skills.

The paper outlines ten practices every computational biologist should adopt when writing code for research computing. Most of these are the usual suspects that you’d probably guess – using version control, workflow management, writing good documentation, modularizing code into functions, unit testing, agile development, etc. One that particularly jumped out at me was the recommendation to document design and purpose, not mechanics.

We all know that good comments and documentation is critical for code reproducibility and maintenance, but inline documentation that recapitulates the code is hardly useful. Instead, we should aim to document the underlying ideas, interface, and reasons, not the implementation. (emphasis added)

There is no shortage of advice (largely unread) on good writing practices. šŸ˜‰

Stephen calling out the advice to “…document design and purpose, not mechanics” struck me as relevant to semantic integration solutions.

In both RDF and XTM topic maps, the same URI as an identifier is taken as identifying the same subject.

But that’s mechanics isn’t it? Just string to string comparison.

Mechanics are important but they are just mechanics.

Documenting the conditions for using a URI will help guide you or your successor to using the same URI the same way.

But that takes more than mechanics.

That takes “…document[ing] the underlying ideas, interface, and reasons, not the implementation.”

February 6, 2013

Improving User Experience in Manuals

Filed under: Documentation,Writing — Patrick Durusau @ 2:49 pm

Improving User Experience in Manuals by Anastasios Karafillis.

From the post:

The manual: possibly the most awkward part of a userā€™s experience with a product. People avoid manuals whenever possible and designers try to build interfaces that need not rely on them. And yet, users and designers would certainly agree that you simply must provide a proper manual.

The manual can be a powerful tool for unleashing the full potential of an application, something of benefit to users and vendors. Why is it, then, that manuals so often seem to confuse users rather than help them?

Letā€™s look at the most common difficulties faced by technical writers, and how to best deal with them to improve the user experience of manuals.

“…a proper manual.” Doesn’t seem to be a lot to ask for.

I have seen some better than others but they were all fixed compromises of one sort of another.

Ironic because SGML and then XML advocates have been promising users dynamic content for years. Content that could adopt to circumstances and users.

Instead we gave them dead SGML/XML trees.

What if you had a manual that improved along with you?

A manual composed of different levels of information, which can be chosen by the user or adapted based on your performance with internal tests.

A beginning sysadmin isn’t going to be confronted with a chapter on diagnosing core dumps or long deprecated backup commands.

A topic map based manual could do that as well as integrate information from other resources.

Imagine a sysadmin manual with text imported from blogs, websites, lists, etc.

A manual that becomes a gateway to an entire area of knowledge.

That would be a great improvement in user experience with manuals!

January 19, 2013

Documentation: It Doesnā€™t Suck! [Topic Maps As Semantic Documentation]

Filed under: Documentation,Topic Maps — Patrick Durusau @ 7:08 pm

Documentation: It Doesnā€™t Suck! by Jes Schulz Borland.

documentation illustration

Jes writes:

Some parts of our jobs are not glamorous, but necessary. For example, I have to brush Brentā€™s Bob Dylan wig weekly, to make sure itā€™s shiny and perfect. Documentation is a task many people roll their eyes at, procrastinate about starting, have a hard time keeping up-to-date, and in general avoid.

Stop avoiding it, and embrace the benefits!

The most important part of documentation is starting, so Iā€™d like to help you by giving you a list of things to document. Itā€™s going to take time and wonā€™t be as fun as tuning queries from 20 minutes to 2 seconds, but it could save the day sometime in the future.

You can call this your SQL Server Run Book, your SQL Server Documentation, your SQL Server Best Practices Guide ā€“ whatever works for your environment. Make sure itā€™s filled in for each server, and kept up to date, and youā€™ll soon realize the benefits

There is even a video: Video: Documentation ā€“ It Doesnā€™t Suck!.

Semantic documentation isn’t the entire story behind topic maps but it is what enables the other benefits from using topic maps.

With a topic map you can document what must be matched by other documentation (other topic maps, yours or someone else’s), for both to be talking about the same subject.

And you get to choose the degree of documentation you want. You could choose a string, like owl:SameAs, and have a variety of groups using it to mean any number of things.

Or, you could choose to require several properties, language, publishing house, journal, any number of properties, and then others are talking about the same subject as yourself.

Doesn’t mean that mis-use is completely avoided, only means it is made less likely. Or easier to avoid might be a better way to say it.

Not to mention that six months or a year from now, it may be easier for you re-use your identification, since it has more than one property that must be matched.

January 12, 2013

13 Things People Hate about Your Open Source Docs

Filed under: Documentation,Open Source,Software — Patrick Durusau @ 7:06 pm

13 Things People Hate about Your Open Source Docs by Andy Lester.

From the post:

1. Lacking a good README or introduction

2. Docs not available online

3. Docs only available online

4. Docs not installed with the package

5. Lack of screenshots

6. Lack of realistic examples

7. Inadequate links and references

8. Forgetting the new user

9. Not listening to the users

10. Not accepting user input

11. No way to see what the software does without installing it

12. Relying on technology to do your writing

13. Arrogance and hostility toward the user

See Andy’s post for the details and suggestions on ways to improve.

Definitely worth a close read!

November 23, 2012

Javadoc coding standards

Filed under: Documentation,Java — Patrick Durusau @ 11:30 am

Javadoc coding standards by Stephen Colebourne.

From the post:

These are the standards I tend to use when writing Javadoc. Since personal tastes differ, I’ve tried to explain some of the rationale for some of my choices. Bear in mind that this is more about the formatting of Javadoc, than the content of Javadoc.

There is an Oracle guide which is longer and more detailed than this one. The two agree in most places, however these guidelines are more explicit about HTML tags, two spaces in @param and null-specification, and differ in line lengths and sentence layout.

Each of the guidelines below consists of a short description of the rule and an explanation, which may include an example:

Documentation of source code is vital to its maintenance. (cant)

But neither Stephen nor Oracle made much of the need to document the semantics of the source and/or data. If I am indexing/mapping across source files, &ltcode> elements aren’t going to be enough to compare field names across documents.

I am assuming that semantic diversity is as present in source code as elsewhere. Would you assume otherwise?

November 6, 2012

Meet the new Light Table

Filed under: Documentation,Programming — Patrick Durusau @ 5:22 pm

Meet the new Light Table by Chris Granger.

From the post:

We have to start with a picture. Or hey, just go download it and see for yourself.

Light Table

This is the new Light Table – rewritten from the ground up after having learned a ton about what it’s going to take to make a truly extensible and connected environment. There are a lot of interesting ideas under the hood that make up the core of this new implementation, but the important part is that it is a solid foundation for us to continue forward on. The new code is not only smaller, but far more robust, and allows us to iterate incredibly quickly.

But the changes aren’t just all under the hood. What we have here is far more useable and useful than what we had before. As a matter of fact, I realized the other day that the only time I actually open vim now is when I manage to hose my instance of Light Table. The environment is entirely bootstrapped with all of our work happening by modifying Light Table at runtime. Even I’m amazed at the difference that this has made and it’s something I think you just have to experience to really appreciate – writing whole features without refreshing the screen once is a truly gratifying experience, one we intend to bring to everyone.

BTW, the material on the right side of the screen shot is evaluation of code as it is entered. Plus Light Table offers very nice documentation handling.

A number of ideas about iDEs that find expression in Light Table. Individually interesting but not impressive ideas.

In combination, however, well, run Light Table and see for yourself.

September 20, 2012

“Communicating the User Experience” (Book Review)

Filed under: Documentation,Interface Research/Design,Usability — Patrick Durusau @ 7:47 pm

“Communicating the User Experience” – reviewed by Jane Pyle.

From the post:

Iā€™ll admit it. I havenā€™t spent a lot of time in my career creating beautiful wireframes. For the past four years Iā€™ve been designing mobile apps for internal use in a large corporation and the first casualty in every project has been design documentation. Iā€™ve been able to successfully communicate my designs using sketches, dry erase boards, and/or rapid prototyping, but the downside of this approach became quite clear when our small team disbanded. As a new team was formed, the frequently asked question of ā€œso where is the documentation for this projectā€ was met with my sheepish gaze.

So I was very curious to read Communicating the User Experience and perhaps learn some practical methods for creating UX documentation on a shoestring time budget. What’s the verdict? Have I seen the documentation light and decided to turn over a new leaf? Read on.

As Jane discovers, there are no shortcuts to documentation, UX or otherwise.

A guide to tools for creating a particular style of documentation can be helpful to beginners, as Jane notes, but not beyond that.

Creating documentation is not a tool driven activity. It is a more creative activity than creation of software or an interface.

Software works with deterministic machines and can be tested as such. Documentation has to work with non-deterministic users.

The only test for documentation being whether it is understood by those non-deterministic users.

Rather than facing the harder task of documentation, many prefer to grunt and wave their sharpies in the air.

It may be amusing, but it’s not documentation.

June 4, 2012

Whereā€™s your databaseā€™s ER Diagram?

Filed under: Database,Documentation — Patrick Durusau @ 4:32 pm

Whereā€™s your databaseā€™s ER Diagram? by Scott Selikoff.

From the post:

I was recently training a new software developer, explaining the joys of three-tier architecture and the importance of the proper black-box encapsulation, when the subject switched to database design and ER diagrams. For those unfamiliar with the subject, entity-relationship diagrams, or ER diagrams for short, are a visual technique for modelling entities, aka tables in relational databases, and the relationships between the entities, such as foreign key constraints, 1-to-many relationships, etc. Below is a sample of such a diagram.

Scott’s post is particularly appropriate since we were talking about documentation of your aggregation strategy in MongoDB.

My experience is that maintenance of documentation in general, not just E-R diagrams, is a very low priority.

Which means that migration of databases and other information resources is far more expensive and problematic than necessary.

There is a solution to the absence of current documentation.

No, it isn’t topic maps, at least not necessarily, although topic map could be part of a solution to the documentation problem.

What could make a difference would be the tracking of changes to the system/schema/database/etc. with relationships to the people who made them.

So that at the end of each week, for example, it would be easy to tell who had or had not created the necessary documentation for the changes they had made.

Think of it as bringing accountability to change tracking. It isn’t enough to track a change or to know who made it, if we lack the documentation necessary to understand the change.

When I said you would not necessarily have to use a topic map, I was thinking of JIRA, which has ample opportunities for documentation of changes. (Insert your favorite solution, JIRA happens to be one that is familiar.) It does require the discipline to enter the documentation.

March 24, 2012

Best Written Paper

Filed under: Documentation,Writing — Patrick Durusau @ 7:36 pm

Best Written Paper by Michael Mitzenmacher.

From the post:

Daniel Lemire pointed to an article on bad writing in science (here if you care to see, not CS-specific), which got me to thinking: do we (in whatever subcommunity you think of yourself being in) value good writing? Should we?

One question is what qualifies as good writing in science. I’m not sure there’s any consensus here — although that’s true for writing more generally as well. While colorful word choice and usage can garner some attention* (and, generally, wouldn’t hurt), unlike what some people may think, good writing in science is not a vocabulary exercise. I find that two key features cover most of what I mean by good writing:

  1. Be clear.
  2. Tell a story.

Those two points cover “good writing” for all types of writing.

March 15, 2012

Documenting decisions separately from use cases

Filed under: Decision Making,Documentation,Information Integration,Use Cases — Patrick Durusau @ 8:02 pm

Documenting decisions separately from use cases by James Taylor.

From the post:

I do propose making decisions visible. By visible, I mean a separate and explicit step for each decision being made. These steps help the developer identify where possible alternate and exception paths may be placed. These decision points occur when an actorā€™s input drives the scenario down various paths.

I could not have put this better myself. I am a strong believer in this kind of separation, and of documenting how the decision is made independently of the use case so it can be reused. The only thing I would add is that these decisions need to be decomposed and analyzed, not simply documented. Many of these decisions are non-trivial and decomposing them to find the information, know-how and decisions on which they depend can be tremendously helpful.

James describes development and documentation of use cases and decisions in a context broader than software development. His point on decomposition of decisions is particularly important for systems designed to integrate information.

He describes decomposition of decisions as leading to discovery of “information, know-how and decisions on which they depend….”

Compare and contrast that with simple mapping decisions that map one column in a table to another. Can you say on what basis that mapping was made? Or with more complex systems, what “know-how” is required or on what other decisions that mapping may depend?

If your integration software/practice/system doesn’t encourage or allow such decomposition of decisions, you may need another system.

James also cover’s some other decision management materials that you may find useful in designing, authoring, evaluating information systems. (I started to say “semantic information systems” but all information systems have semantics, so that would be prepending an unnecessary noise word.)

March 9, 2012

BIā€™s Dirty Secrets ā€“ The Unfortunate Domination of Manually-Coded Extracts

Filed under: BI,Documentation — Patrick Durusau @ 8:44 pm

BIā€™s Dirty Secrets ā€“ The Unfortunate Domination of Manually-Coded Extracts by Rick Sherman.

From the post:

Manually-coded extracts are another dirty secret of the BI world. Iā€™ve been seeing them for years, in both large and small companies. They grow haphazardly and are never documented, which practically guarantees that they will become an IT nightmare.

How have manually-coded extracts become so prevalent? Itā€™s not as if there arenā€™t enough data integration tools around, including ETL tools. Even large enterprises that use the correct tools to load their enterprise data warehouses will often resort to manually-coded extracts to load their downstream BI data sources such as data marts, OLAP cubes, reporting databases and spreadsheets.

I thought the following passage was particularly good:

….Tools are easy; concepts are harder. Anyone can start coding; itā€™s a lot harder to actually architect and design. Tool vendors donā€™t help this situation when they promote tools that ā€œsolve world hungerā€ and limit training to the tool, not any concepts.

I don’t see manual coding as a problem, so long as it is documented. There should be one and only one penalty for lack of documentation. Termination.

Lack of documentation can put critical IT systems at risk and it doesn’t take complex systems to produce. Even (gasp) MS Word documents that are maintained with a table of contents and indexes can be adequate documentation.

Not the same as a bug database with bug reports, patches, pointers to code, email discussions, meeting minutes, etc., but interactive production of graphs and charts isn’t a requirement for successful documentation.

Undocumented manually-coded extracts are a sign that the requirements of BI users are not being meet. Getting those documented and incorporated into BI tools looks like a good first start to solving this secret.

February 22, 2012

Economist Style Guide

Filed under: Documentation — Patrick Durusau @ 4:47 pm

Economist Style Guide

The Economist’s style guide is back online!

Following this style guide will make your documentation successful. Up to you if your software is as well.

Example of brevity from the style guide:

Passive

Be direct. Use the active tense. A hit B describes the event more concisely than B was hit by A.

Compare The Chicago Manual of Style (15th edition) at a 1/3 of a page or The Hodges Harbrace Handbook (17th edition) at 3 pages. Both have amusing examples and details but sometimes you just want the bare rule.

September 8, 2011

Cheatsheets

Filed under: Documentation — Patrick Durusau @ 6:01 pm

Cheatsheets

I was looking at some Hadoop output today and wishing I had a quick cheatsheet at hand.

I didn’t find one but I did find this site devoted to cheatsheets.

There were two (2) for Hadoop (DZone) but they were both concerned with what I type and not messages I may or may not see in return.

I am sure it is in the documentation but does anyone have a pointer to a message cheatsheet for Hadoop?

May 5, 2011

Editing Geeks

Filed under: Documentation,Marketing,Standards — Patrick Durusau @ 1:55 pm

Top 25 Blogs for Editing Geeks

Something for those of us who are concerned with documentation and standards.

There is a lot of documentation, not to mention standards, in the topic maps area that could use attention.

Rather ironic that documentation for topic maps should be sub-par since the topic maps adventure started off as a software documentation project.

Perhaps getting our own house in order might make topic maps more appealing to others as well as giving all of us better documentation for existing topic map applications.

« Newer Posts

Powered by WordPress