Documentation Outline - strategy

[plwalters]

As a kickstarter to the conversation here are some things we are hoping to hear back on. Feel free to number your responses and keep them as short as needed but as long as necessary -

1. What is your favorite or easiest to use documentation? (ex. Bootstrap 3.2 docs)
2. What topic(s) should we prioritize next in documentation?
3. What is one must have feature of the documentation?

[devmondo]

!!First!! i really like ravendb docs style http://ravendb.net/docs/article-page/3.0/csharp/welcome good parts

you can choose a version and docs will reflect that

the left navigation has collapsible sub topics

[TheCodeDestroyer]

@devmondo +1 Also, it would be awesome to have a live example of the code with a test, like on AngularJS Docs

[davidpeden3]

1. Stripe's docs and api reference are both fantastic

[fopsdev]

@TheCodeDestroyer +1 for editable test backed docs like AngularJS Docs

[jdanyow]

For the API piece, I like this:

The links take you to the method/property/event details which include info about the arguments etc and a link to the actual line in the source code where it's defined.

[EisenbergEffect]

@jdanyow What do you think of this: http://durandaljs.com/documentation/api.html That was basically a durandal app built on top of the yuidoc json data.

[plwalters]

For the API reference I think it should be very easy to find and navigate through so the one issue I had in the beginning with the Durandal docs was that I wasn't sure exactly where to go to find what I was looking for. Searchable should be a big part of that left hand nav if possible. The breeze docs are very similar but a little easier to navigate.

Looking at what @davidpeden3 mentioned in the stripe docs, I also really like that direct example pane beside the API reference. It seems to fit in nicely with the post that @jdanyow did on ValueConverters as well.

As far as the actual documentation I want to go through each of the mentioned docs above to look at some of the best practices and see some common themes that stick out so if there are any particular points in the docs that are linked that people like, please mention here.

[jdanyow]

@PWKad agree @EisenbergEffect I like the durandal API docs too- they have the click through to source feature which is nice.

The modular, versioned documentation approach is going to be really maintainable but we may need to add some logic in the docs app to tie everything together. Maybe an API search that works across all the modules?

Not sure how large the JSON gets for the api docs certainly could be compressed and cached in local storage. Would be something we do off the UI thread using a web worker.

[devmondo]

also, if i may suggest, instead of this in current docs "Note: Looking for this guide in another language? Have a look in our documentation repo."

why don't we have a drop down menu or list for languages ?

[adriatic]

I got used to Pluralsight concept of narrated courses which use their proprietary player (which would be quite cool Aurelia app by the way). This may be perceived as a "task too big" for a small company, but before making that conclusion, it may be worth thinking about a bit as I am sure that this could be done by some good hearted people who love Aurelia. My point (coming from several very painful memories from my own past where I managed the complete software development) that having world class documentation is as important as the software product itself.

[adriatic]

In terms of documentation priorities: my view is that Custom Elements might just be the most appealing single Aurelia feature (not to degrade any others). I have a number of very important such elements in my to do queue for the app I am planning to create with Aurelia

[lneffa]

My main frustration with the Durandal docs , and hopefully not the case with Aurelia, is the huge blocks of text with a poor ratio of code to explanation. I read through a lot of the text / explanations, and had to navigate many links inside the api docs on a separate window. From my experience, the explanations are much better than the api docs. I ended up having to also read through the google forum and find sample blocks of code to match explanations.

I also want to mention that the way the explanations are laid out across the Durandal site made it hard to keep log of what I have and have not read through. I like to read through as much as I can and know where I stand. When first learning Marionettte's functionality, these docs http://marionettejs.com/docs/current/ made it simple for me to keep track.

[plwalters]

@audeamus22 Excellent feedback, thanks for the insight. We definitely want to make code samples a first class priority. I am hoping to propose a draft with a wireframe in here today so we can begin the heavy lifting of getting everything to work together. Thanks again!

[plwalters]

@adriatic Great feedback as well, I love the flexibility in composition in Aurelia the most and hopefully we can make the documentation easy to read on that topic so it is recognized by everyone else as well.

[adriatic]

@PWKad @EisenbergEffect As Rob will undoubtedly confirm I am a really big fan of Aurelia and as a developer of very complex applications I will be more than happy to help with any documentation related tasks (use case scenarios, sample design, etc)

[lneffa]

@PWKad great, real great. I would say most teams would be looking forward to read as much as possible this weekend on any sort of gathered documentation, fancy or not, because come weekdays the rubber meets the road. :)

[coderbynoon]

I posted this on the Aurelia gitter forum, and was asked by jdanyow to re-post it here.

My $.02 as a JS Framework newbie. 10+ years .NET dev. JS developer for 1 year using Durandal. I knew some JS (very limited) before Durandal, but Durandal "just worked" and very easy to setup. Really the only thing I spent some extra time on was learning about require.js/r.js for build/bundle options. As I've been following this group and the progress of Aurelia, I'm discovering there are a lot more technologies/tools involved outside of the framework itself. Here's a short list of things I've noted that I may need to become more knowledgeable in when I upgrade to Aurelia. For experienced JS devs most of these are part of your everyday toolbox. Depending on who the upcoming books/courses are targeted to, this may give ideas on what to have as prerequisites or have some initial coverage on, especially if targeted towards beginners.

Getting the code node/gulp/jspm - What are these, how to set them up, and use them during the dev process? In Durandal (using VS) I could just download the latest release, copy the js files into my project and I'm off coding (look mom, no Node!). Is that type of process even supported with Aurelia? I'm thinking "no" since Aurelia has a more building-block architecture, and these tools aid in pulling in what is needed, as well as providing other services.

Development process TypeScript, ES6, Traceur, Babel (6to5), transpiler - What are all these? Are they required? What are my options? Upgrading a Durandal app to Aurelia will probably touch on some of these. Maybe. I don't know. I would love to see a video of the Welcome/Flickr sample app converted from Durandal to Aurelia. (If there are multiple end states in Aurelia using different technologies, then show multiple conversions)

Build/Bundle I know a lot of effort is being put into this, along with some feature requests for the package manager. I think this is OK to have as a black box as long as devs follow whatever conventions are recommended. If you deviate from the conventions, then you probably know enough to do so.

Thats my $.03

[TheCodeDestroyer]

Also, it would be nice if the docs are written in markdown and most importantly a button for "Improve the docs" should be there so that the community can help you document the framework.

[plwalters]

WITHOUT FURTHER ADO... ( @EisenbergEffect )

Here is the proposal -

Summary

Docs for each app will be changed to a version controlled directory format. The format will be the directory doc and then the semver version. Ex -

- dependency-injection
| - doc
| | - 0.5.0

Inside will be the docs, api.json, and package.json files. The current doc generation task needs to be altered to match the above output at time of release. Once the release is ready the task will run. There will be an additional new gulp task gulp push-docs-to-azure or something similar. An optional modifier would be a specific version like gulp push-docs-to-azure -v 0.5.2 in case it isn't the most recent version you are pushing.

The azure blob storage will be set up in a similar fashion, but changed slightly. It will have a parent container aurelia that holds each blob. Since blob storage doesn't support directories the files will be named to simulate that like so - dependency-injection/0.5.0/doc/api.json

Once the files are on the CDN the CDN needs CORS enabled. The app will have the ability to choose a repository and also choose a version. The version will be from available versions, not sure how to deduce this entirely yet. The big question here is how to 'package' that version of the repo into a set of docs so that while you are switching between them it isn't always jumping to latest.

The package.json can probably be used for this purpose. Currently the doc demo at http://104.236.214.120/#/Repository/1 shows choosing a repository (It should be a single line fix to move to pulling from azure once CORS is enabled) and seeing the classes, methods, properties, and events. The TODOs on the doc app is to share the same views and viewmodels and add the versioning mentioned above.

[MicahZoltu]

I consider MSDN the gold standard for API documentation. Every public type, method, enum, etc. is documented. Very important is the fact that items are linked together. This means if I go look at some method that takes in a type as a parameter, there is a link over to the type's page.

I understand that JavaScript is not a statically typed language, which I consider to be unfortunate, but a good framework should be written as though it were statically typed for the most part. This means that if you have a method that takes an object as a parameter there should be a page that details the type of that parameter. Also, if you are interacting with third party libraries link out to the appropriate API documentation at each of those interaction points.

As an example, I can dependency inject a router into a class constructor. I would like to see documentation on the router type that includes the methods I can call on it and the properties I can access. In the case of router, it has a configure method I can call that takes in some parameter(s). These parameters would be listed in the documentation and each parameter would have a link to its type definition documentation page unless it is a primitive (string, number). If it expects a function or an object with an expected structure then there should be links to the documentation for that function/object.

In general, it seems that most JavaScript frameworks/libraries have pretty poor documentation. I believe this is a side effect of being a dynamic language so you can't auto-generate documentation like you can in a static language. Using MSDN as an example, the documentation all comes from the source code and because it is statically typed a document generator can correctly link things together. Working with JavaScript makes this much harder for the framework developer, but still just as valuable.

[delebash]

I have been looking into documentation for a users app for both js and css. For js documentation I like https://github.com/tj/dox, since it just outputs a .json file which can then be bound to a template to our liking as the default else a user can create there own aurelia template. I also came across http://apidocjs.com/ example output http://apidocjs.com/example/ which I also like as a template, but you def need search abilities and ability to choose api version.

CSS kss-node https://github.com/kss-node/kss-node, kss seems popular and the kss-node project seems alive and well. I like this for that same reason, you can output just a json file and bind it to a custom template of your making. I already have a small gulp task that outputs the json file from kss-nodes api.

If this is something you are interested in let me know, else if you already have plans for something different already in the works with aurelia-cli, then I will stop working on this and wait, or I can pitch in to aurelia-cli documentation if you let me know what you have in mind.

Biggest thing for me is that I like generators that just output .json, this way anyone can create a custom template for viewing of course we will provide a default.

[EisenbergEffect]

@scriswell Please review this thread in preparation for our meeting on Thursday. This aggregates a bunch of thoughts from the community on documentation.

[scriswell]

@EisenbergEffect will do.

[EisenbergEffect]

Thanks everyone for the feedback. We are beginning design of the new docs now and will be taking this into account.

[pasky]

This seems to be as good a place to leave feedback as any - I've been using Aurelia for a few weeks and my number one hurdle is how hard it is to google out information.

If you are lucky, someone's last year blogpost will share some tricks (which may or may not be up to date with current Aurelia), but the official Aurelia docs are as good as non-existing in this regard because they never come up in the search.

For example, I wanted to find an exact description of what model.bind does. I still don't know if that exists in Aurelia's docs, because the built-in search doesn't even find the brief mention in the cheatsheet; even if it did, it's extremely unlikely to work as well as Google does.

Figuring out a way to fix that would be a major step ahead in usability of Aurelia for new developers, imho. Showcasing Aurelia as its own docs browser is a nice idea, but I think it shows as one of the thoroughly unsuitable usecases for a single-page app in the end. What do you think?

[scriswell]

We're always working on our docs and improvements to the new search index are ongoing. As for search engine results like those found with Google we are working on building features into Aurelia that will allow for excellent SEO optimization. These features are part our our server side rendering updates that we're working on now. We will of course be dogfooding this in our own apps to insure a first-class dev experience. The Aurelia HUB is no exception.

The HUB is very forward thinking but it is still in beta (with much more to come) and will improve in many ways during the official beta period, including those updates mentioned above. Also, more articles are in the works to help people grow with Aurelia. Stick with us during the beta and thank you for your feedback and continued support of Aurelia.

[pasky]

Awesome, I'm just happy to hear that you have this in your crosshairs. :)