Please hire a competent technical writer #1036
Comments
|
Hi, Sorry you had a bad experience. To respond to two specific points:
Cheers, |
|
Thanks for adding the code. Too late for me, but I'm sure others will appreciate it. Re the tutorial to which I linked, the second paragraph below the table of contents begins:
Testing is apparently not your forte. Here is an alternative response you could have given: "Wow! Thank you for this painful but important critique. I had no idea. You are right: we should be testing this material. And no doubt there is a large body of best practices that we could adopt to improve the documentation and other learning materials. Can you provide links to the resources you've found most useful? A list of specific suggestions and why you think they'd be an improvement would also be helpful. I am eager to move forward with this and hope you can spare the time. Maybe you could write an example tutorial for us?" Which is the truly professional response, yours or mine? Which stands to benefit both Polymer and its early adopters? Which is more likely to convert me from a very angry critic to a potential source of high quality, free and mutually-beneficial help? |
|
@chasm - I am having luck looking at the documentation for each element. Here is link to the scaffold, https://www.polymer-project.org/docs/elements/core-elements.html#core-scaffold, which has a demo button at the top with no obfuscation. Directly, it may not be comprehensive of all things style, data binding, layout attributes, etc; however, if you view the source of the imported polymer-element(s), then you'll likely encounter concepts, constructs and snippets similarly found in the API developer guide, https://www.polymer-project.org/docs/polymer/polymer.html. It is not the top down tutorial of your wildest dreams but hope it helps. |
|
Hi, Jon, Thanks for your suggestions. That's pretty much what I've been doing. It's slow going, but eventually I figure it out. I appreciate the help. Believe me, I have been scouring the Internet for anything and everything I can find. That said, what you offer is a workaround, not an improvement. The question is, if writing tutorials anyway, why not make them the top-down tutorials of my wildest dreams? It doesn't really take much more effort, and it will save orders of magnitude of effort on the part of readers. I could understand if Polymer was five guys in an incubator with no funding, but this is Google, isn't it? |
|
While being in progress of building a pretty complex app in pure Polymer right now I found the codumentation to be fair with regards to the state the frameworks it is in (young). Some components are not very well documented or demoed, but with some inspection it is easy to find out - I assume the core components is in change still so writing a lot of docs or autogenerating "OOP docs" is probably not a good focus. Using Scala API (Java) style documentation as "good" example of documentation is pretty big assumption that all programmers find that a good way of organising docs. If Polymer was documented like that I wouldn't have touched it with a stick, and then I have spent my fair part of reading such document structures my days. I believe at the current stage the current document format is ideal, especially for beginners. Pretty good work on the docs so far IMO, though some room for enhancement of course. One would be inline test suits for the different parts/components (in |
|
Hi. As the author of that article I need to chime in here :) All of our articles assume the reader has worked with Polymer before. As others have pointed out, we have great intro/starter material elsewhere that fills the void for beginners. On a personal note, I dislike tutorials/articles that cover every little detail. They're tedious and painful to sift through. I prefer "short, sweet, to the point" and a lot of our developers do too. The goal of this particular article was to teach developers how to build a specific type of app, not learn Polymer. "How do I take what I know and apply it to this concept". Totally agree about the downloadable code. It requires rearranging the code which is why it fell off our radar. Until then, the code is in the docs repo. |
|
Wow. It just gets worse. This doesn't seem to be worth pursuing further. Rather than show any interest in how the documentation could be significantly improved -- perhaps with a concomitant uptick in Polymer adoption -- it's all about circling the wagons. A shame. |
|
@chasm as a fellow polymer novice and outside community member, I share many of the same feelings about how the documentation and initial developer experience can be improved. I participated in a Polymer hack day recently that had a lot of slow starts and delays because of the framework bundling and tutorial ramp-up process. That said, I think it's undeniable that Polymer is a great community of genuinely talented and caring people who want to make the developer experience the best possible. Polymer is equally, if not more technically complex and ambitious in many areas than AngularJS. Just try to remember how difficult it was for novices to understand Angular just a couple years ago. Maybe you could reconsider that the title of this issue could have been read as extremely insulting and aggressive (not to mention the rampant frustration in the description), dial it back a bit, dig in and submit a couple small pull requests to fix the areas your talking about. That's how the best community will develop. I agree with your spirit if not your phrasing, so if there's anywhere I can lend a hand, I'm happy to help. |
|
@chasm I wouldn't classify a documentation like the one at http://www.scala-lang.org/api/current/#package an improvement, but a real good sample of the kind of documentation which draws me immediately away from any library/tool I see. So preferences and expectations are obviously different. It's so easy to complain. But it's open source, so why don't you help to improve? Every journey starts with a small step... |
|
Doesn't anyone here understand the difference between anecdotal evidence and serious testing? Your personal reaction to a style of documentation is irrelevant. You need to test. And rather than reinvent the wheel, you could also do some research and learn what has worked best according to the literature. The Scala API is a reference work, like a dictionary. As such, it's not something you learn from, it's something you use to remind yourself of syntax and relationships. Sorry you find it scary. You might ask the Scala community how useful they find their API documentation. I'm betting the answer is very. Such a reference must be accompanied by short, specific, clear, and complete explanations for how to accomplish the most common tasks. Each should be fairly self-contained so that users can -- after only a very brief introduction -- apply the framework to the task they need it for. How many developers who are working for a client have time to build apps unrelated to their needs just so they can learn a framework? The most efficient way to onboard new developers would be for them to have the ability to mix and match atomic units of information such that their "training program" taught them exactly what they needed to know, exactly when they needed to know it, so they could apply it immediately. I call this Just-In-Time Learning™. I mean, am I missing something, or isn't Polymer about componentization? Why can't you apply this equally to your documentation? Speaking of which, would you release Polymer code without testing it? I hope not. Do you have a style guide for your coding practices? Do you manage the project using some project management tool? How about a set of milestones and a map for future development? I would assume that a project of this magnitude would have all of the above. So do you have the same for your documentation? Is it tracked? Do you have a map for what needs to be done and in what order? Do you have a system for updating out-of-date material or at least marking it deprecated or obsolete? Do you have a testing protocol using developers new to Polymer (not developers who already know Polymer!)? If not, why not? There is a significant hurdle to learning Polymer from scratch. This tends to create insular communities where everyone has "paid his dues" by learning using trial by fire. And that tends to create smug, self-satisfied developers who don't want to make it easy to learn the framework because they feel it devalues the hard work that they had to put in to learn it. Those who complain are simply dismissed as not bright enough or not sufficiently motivated. Forgive me if I find this arrogance replusive. You think I should help? What do you think I've been trying to do? Read the above commentary. I believe that I gave not only specific examples of problems with the documentation, but also specific suggestions for how to improve it. And I'd be happy to give many more. In contrast, please show me even one instance above -- except for promising to link to the code -- where the Polymer team even admitted that there could be improvement, let alone discussed how to go about it, or asked for clarification or further suggestions. I've already contributed thousands of dollars to Polymer -- my time to learn it at about 20% effectiveness thanks to the poor documentation, and several hours responding here. And for this effort I have received what? Nothing but more aggravation. Thanks, but I think we're done here. |
|
@chasm Polymer is currently at version 0.5, while Scala is at version 2.11. Polymer is extremely new, whereas Scala has been around since 2003. In my opinion, spending massive amounts of time on documentation at this point would be a huge waste. Things are still changing rapidly, and the ecosystem as a whole is still evolving. While I agree that a 1.0 release should have much of that, I surely don't expect a 0.5 to have it, especially when it is so new. Compare the state of polymer's documentation with Scala's from the early days. Here is an example from archive.org from 2007, about 4 years after the language was introduced. |
|
Klathmon, that is sheer nonsense. The current Polymer documentation is overly verbose. How would it take any more time to do something more concise? The difference is mostly one of style. And how will it help Polymer to spend significant resources writing today's documentation, only to have to rewrite it all later? Why not just do it right from the beginning? That's less to change later. And shouldn't each new project build on the lessons of projects that have come before? Why would you want to go backwards to 2007 and start there? The Scala team has spent a lot of time and effort making the best API documentation possible. All Polymer has to do is reap the benefits of that effort. This is more circling the wagons. It's clear that the Polymer team doesn't think anything needs changing, and resents the claim that it does. Not one respondent here has shown the slightest interest in improving the documentation or even been willing to admit that there might be something fundamentally wrong with their approach. The better the documentation, the higher the rate of adoption. The higher the rate of adoption, the more people available to help with code, suggestions, critiques, etc. The more help, the faster Polymer reaches that 1.0 goal and the better its market share against the competition -- which means the more likely that all this effort will not have gone to waste. It is very clear from the responses here that it's not at all about improving Polymer; it's about bruised egos and chasing away the threat. |
|
@chasm I am pretty sure Polymer core team they would accept a pull request. Use the energy for contributing instead, the point of open source. For the record I learned most I need to know to build a fully fledged Polymer app within a few hours of tinkering around, that is far far less than what it took me to get Angular, and other similar frameworks. Really enjoy Polymer last few weeks. |
|
❤️ this thread, 🍰 and polymer documentation |
Because its impossible to document things that haven't been written yet? Just a few weeks ago, they changed a core piece of how icons work with paper-items, they are most likely going to be changing a massive number of things (many breaking) in version 0.8. Things are still changing. Not just the documentation but core platform features, if you can document future changes before they happen please submit a pull request as your ability is sorely needed. |
|
Nothing in my critique was about coverage. I was clearly referring to the style and organization of the documentation -- how it is being presented. That presentation could have been done in any number of ways, whether you are documenting one thing or one million. Coverage doesn't enter into it. But it makes a nice straw man, no? There are plenty of examples of excellent tutorials out there. I already gave the API example of the Scala docs -- Ruby, Rails, and pretty much every other language and/or framework has a similar style. Here is an example of a very good tutorial, far better than anything that Polymer has put out: http://code.tutsplus.com/tutorials/using-polymer-to-create-web-components--cms-20475 These are far from perfect -- they could be improved significantly -- but they are better than most. There is a great deal of prior art out there that could serve as an example. That your core group of experts likes the documentation as-is is meaningless, unless they constitute the only users you want. If you would rather see high adoption rates early on by average developers, maybe you should ask some of them how your documentation could be improved. |
Polymer is an exciting development, but the current documentation seems intended to alienate new users. It stands to reason that Google would like to see rapid adoption of Polymer and related technologies. Poor documentation is antithetical to that goal.
Here is an example of well done API documentation: http://www.scala-lang.org/api/current/#package
Note the search field. Note the compact and consistent format. Note that users can easily search by elements and attributes (i.e., classes, objects, methods, and properties). Note that there are explanations where needed but they are short and sweet, and there is always a very clear synopsis. I can practically teach myself Scala from this API alone.
In addition to the API, one needs tutorials. Here is an example of a very poorly done tutorial:
https://www.polymer-project.org/articles/spa.html
I am certain that the author is a terrifically nice guy and a hell of a developer. But has he ever taken a class in technical writing? Does he have any formal training in tutorial writing?
The first rule of a tutorial is that you have to explain everything. Every. Single. Thing.
That's because you never know what your reader will know or not know. Obviously, you cannot recurse infinitely, so you must assume that he or she can at least operate a computer and knows a little about programming, but you can't assume that he or she knows anything about Polymer.
You can link to information that you might (but shouldn't) assume the user already knows, but those links should be to short and sweet and specific information, not to a 50,000 word document that provides the answer 50 paragraphs down. That's not helpful, it's an insult.
Better still, think in CMS terms and create short, atomic explanations of all the basics that readers will need to know. Then put them right in the flow of the tutorial where needed, but collapsed. Hey! I'll bet that they could be reusable web components! What a concept.
Those readers who already know how to do that thing can zip right by it, but those whose memories need refreshing, or who came to this tutorial without having read any others on Polymer, can pop them open and get what they need.
If you look at the above tutorial, the very first code block looks like this:
If I copy and paste that into an empty document and view it in a browser, will it work? Obviously not. It's an HTML fragment, not a full page. And doesn't it require some kind of imports?
Search the above tutorial. See anything in it about imports? See an example of a complete web page?
But, you might say, there's a demo! Yes, let's take a look at that. Nice. A bit too simple -- it would be nicer to see different templates rendered on each menu item click. That's how a real single page app works, right? It's not just a word on each page. But let's not split hairs. The real question is, Where's the code?
Answer: nowhere. There is no obvious "view the code" button. And if you use the page source to view the code, you can find the html for the example, but that won't work if you copy it to your own page. You have to look around until you see that there is an import link that imports something called "vulcanize.html". WTF? View the source of that and it links to "vulcanize.js". View the code and, oh, joy! It's concatenated and minimized. Seriously?
If I wanted to copy this example into my own code and use it -- which I did want to do -- I have to figure out all the imports myself. Why??? Why would you do this to your readers? How difficult is it to provide a complete, unminimized, commented version of the code, linked from the very top of the tutorial, so I can get it up and running as quickly as possible and start playing with it?
In fact, why not link to a GitHub repo and build the tutorial app in stages, committing and tagging each stage with a simple reminder as to how I can clone the app and move from tag to tag to see the app being built. Then you could even do a bit more complicated -- hence actually useful -- example without worrying that it is too complicated. Readers can go only as far as they need to.
I'm sorry if I sound really frustrated, but, seriously, that's Tutorials 101! Shouldn't a company as accomplished as Google have figured this out long ago?
I should be able to come to this tutorial cold and find everything I need to get a reasonable (not oversimplified) single page application up and running, with warnings about all the potential gotchas (that's what sidebars are for, right?). I should be able to start at the top and move through it quickly and be ready to move on twenty minutes later. Instead, it took me _two _days* of frustration* to get it sort-of working, and I'm still not clear what worked, what didn't, and why or why not.
To make sure that this happens, all your tutorials should be tested. What a concept, eh? Test it on a developer who has never used Polymer and doesn't know what it is. Watch and see where she falters. Then fix it.
That might seem a lot of work, but these tutorials will be read by thousands and thousands of potential Polymer converts. If you waste, on average, five hours of their time because you didn't properly anticipate their needs, how do the hours wasted stack up against the author's time? If you don't test and refactor your tutorials, what message are you sending to your readers? Hint: it's not a pleasant one.
The current documentation is verbose beyond belief. To learn the simplest thing requires scrolling through page after page after page of dense verbiage. On the one hand you explain things as if I am utterly ignorant of how to do anything with code; on the other, you leave out key information everywhere. As a result I regularly get 90% of something working, and then spend hours trying to figure out one very minor thing. It's frustrating beyond belief.
And I'm not stupid, and I'm not doing anything really unusual, so I promise you that I am not alone in my frustration. And StackOverflow and a Google Groups are not the answer. They are last resorts! If I have to turn to one of those, I first have to do an enormously difficult search and read all sorts of irrelevant and badly tagged crap just to make sure I don't accidentally ask something that's already been answered. Then I have to do my best to swallow my anger and frustration (not something I do well) to ask the question as sweetly as I can. And then I have to tread water and hope that I get a useful answer. I estimate that the answers I get are useful maybe 25% of the time.
If there were no documentation, I'd put it down to Polymer being brand new. But there is actually a lot of documentation, which makes it seem as if it will all be easy. What a disappointment to discover that the documentation is woefully incomplete, difficult to use, and time-wasting.
Come on, Google! You're supposed to be the smartest guys in the room, no matter the room. Show some of those smarts here and hire an expert in teaching to oversee your Polymer documentation. I'm betting that you'll see adoption rates soar as word gets around.
The text was updated successfully, but these errors were encountered: