The NodaTime Brand

[Matt Johnson]

IMHO, NodaTime could use some brand recognition.

- How about a logo?  Any designers out there?  At least some stylized text would be better than nothing.

- Maybe a vanity domain name?  nodatime.com and nodatime.net are both available.

- Perhaps a clean quick-start site with modern fonts (bootstrap) and instant code samples?

Here are some other libraries that I think are doing it right:

http://autofac.org

http://www.ninject.org

http://momentjs.com

http://jquery.com

http://modernizr.com

http://dotnetopenauth.net

You get the idea...

Also, would someone please update the profile for the @NodaTime twitter account? It needs some description text and and a URL.  When include @NodaTime on a tweet, I'd like the follower to easily get to the project site.

Other thoughts?

[Jon Skeet]

I'm all for these improvements - and would be happy to pay for the web site hosting and domain registration - but I don't have time for all the actual work of it. Given my designs skills, that's probably not a bad thing.

I'm intrigued by the twitter account though. I don't own it - anyone on the list want to come forward?

Jon

--
 
---
You received this message because you are subscribed to the Google Groups "Noda Time" group.
To unsubscribe from this group and stop receiving emails from it, send an email to noda-time+...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Malcolm Rowe]

On 22 May 2013 01:37, Matt Johnson <mj1...@hotmail.com> wrote:

> - Maybe a vanity domain name? nodatime.com and nodatime.net are both
> available.

So's nodatime.org, fwiw.

I'd be very supportive of moving our end-user site to somewhere other
than Google Code, while retaining Google Code for issue tracking, and
so on.

[For one thing, we'll need somewhere else to put new downloads in the
next six months; see
http://google-opensource.blogspot.co.uk/2013/05/a-change-to-google-code-download-service.html.]

But in any case I think we can do a much better job for end-users than
the Google Code landing page does (http://autofac.org/ is a lot closer
to what I'd like to see, though it hides some of the important links
below the fold).

Unfortunately, my HTML/CSS is only workable; I'm no designer.

Regards,
Malcolm

[Jon Skeet]

On 23 May 2013 09:32, Malcolm Rowe <malcol...@gmail.com> wrote:

On 22 May 2013 01:37, Matt Johnson <mj1...@hotmail.com> wrote:

> - Maybe a vanity domain name?  nodatime.com and nodatime.net are both
> available.

So's nodatime.org, fwiw.

Yup. I think I'd prefer a .org address over .com. We could buy both, of course, but I think it would be better to just pick one and be consistent.

 

I'd be very supportive of moving our end-user site to somewhere other
than Google Code, while retaining Google Code for issue tracking, and
so on.

We can probably host it on the same box that hosts csharpindepth.com - I'll contact the main owner.

 

<snip>

Unfortunately, my HTML/CSS is only workable; I'm no designer.

Ditto. Fortunately, we're likely to be able to get a willing designer fairly interested just by a tweet or two. There are advantages to having a  massively inflated and misrepresentative reputation ;)

Will send out feelers and find out more about how it would be most useful to host this. (I have an Azure account could host it, too, for example.)

Jon

[Nathan Palmer]

Alright guys, first draft is done. There are some obvious things to fix in here but wanted to get some feedback. I went with a very simple single page design that linked over to the documentation and nuget packages.

http://d.pr/i/fBiz

Thoughts?

Nathan Palmer

On Sun, Jun 2, 2013 at 1:03 PM, Nathan Palmer <snowp...@gmail.com> wrote:

Well, I saw Jon's tweet and agree with the idea! We did this recently with http://hotglue.info/. Although that actually came from a modified template. However, looking at the sites mentioned you could go anywhere from a simple front-end, like autofac did where all documentation still exists in the code project, to a fuller version such as momentjs and ninject. I fully believe that ninject gained higher adoption due to the it's website (which doesn't look like it has changed much in a while.)

Either way I'm willing to take on the project and can put together some ideas. But I'd like to gather some information on what you guys are looking for having as part of it.

Nathan Palmer

--

[Matt Johnson]

Hi Nathan,

Many thanks for getting this started!  Here is some constructive feedback:

- I like the basic layout - clean and simple.

- I like the colors.  They are distinctive enough to separate this from other libraries.  For example, a black/white page might be too close to momentjs.

- Have we decided, is it "NodaTime" or "Noda Time" (one word or two?)  We should be consistent.  My vote is for one word, but it's up to Jon.

- The clock logo is simple, which is good.  But it doesn't convey much other than its a time library.  Have you considered anything else?

- If the name is to be one word, probably the logo should go on the left or centered above, rather than split up the text.

- I think we can probably come up with better text for the subtitle and left-side.  I assume this is just as a placeholder.  I do like the positioning and layout.

- Probably the sample shown isn't the best "hello world" example.  I like that it shows a zone name and a LocalDateTime, but I think mappings are more of an advanced concept.  Also, the zone shown "Brazil/East" is an alias for "America/Sao_Paulo". But IMHO, we should probably show something very common like "America/New_York" or "Europe/London".

- It would be nice to have multiple samples, either in separate boxes like autofac.org does, or perhaps in the same box with timed rotation and selector.

But overall, great job, and many thanks!

[Nathan Palmer]

Thanks Matt! You are right that some of this is placeholder text although I did pull wording from the existing site/documentation so I'm open to any input you guys have on it. See the rest of my responses inline.

Nathan

On Mon, Jun 3, 2013 at 11:37 AM, Matt Johnson <mj1...@hotmail.com> wrote:

Hi Nathan,

Many thanks for getting this started!  Here is some constructive feedback:

- I like the basic layout - clean and simple.

- I like the colors.  They are distinctive enough to separate this from other libraries.  For example, a black/white page might be too close to momentjs.

- Have we decided, is it "NodaTime" or "Noda Time" (one word or two?)  We should be consistent.  My vote is for one word, but it's up to Jon.

Let me know what you guys think here. The clock on the left or right hand side makes things a bit out of balance. However if you want it together (which I believe I have in the header) I can look for a way to incorporate the icon visual.

 

- The clock logo is simple, which is good.  But it doesn't convey much other than its a time library.  Have you considered anything else?

I considered swapping a letter with the clock but didn't dive too deep into that. The icon was pretty simple to put in there and balanced well in the center. If we can decide on the "Together" vs "Apart" I can revisit.

 

- If the name is to be one word, probably the logo should go on the left or centered above, rather than split up the text.

- I think we can probably come up with better text for the subtitle and left-side.  I assume this is just as a placeholder.  I do like the positioning and layout.

- Probably the sample shown isn't the best "hello world" example.  I like that it shows a zone name and a LocalDateTime, but I think mappings are more of an advanced concept.  Also, the zone shown "Brazil/East" is an alias for "America/Sao_Paulo". But IMHO, we should probably show something very common like "America/New_York" or "Europe/London".

Yes, this is purely placeholder. To be honest one of the short comings to the existing documentation is figuring out exactly "how" you use NodaTime. We need to come up several "quick start" examples that demonstrate how you would commonly use it within an application. This page needs to pass the 12 second test when a user pulls it up and see's the example and immediately will recognize that it provides a benefit (within 12 seconds.) If we have enough good examples I could see expanding this section out to include 4 simple usage examples. It might be useful as well to highlight a proper way to work with timezone's since that seems like the focus of Jon's original "what's wrong with DateTime" post (the ambiguity of it.) I think I'd be looking for someone here on the list to step forward with some ideas though as I haven't written code directly against NodaTime before (just reviewed code that contained it.)

[Jon Skeet]

On 3 June 2013 16:37, Matt Johnson <mj1...@hotmail.com> wrote:

- Have we decided, is it "NodaTime" or "Noda Time" (one word or two?)  We should be consistent.  My vote is for one word, but it's up to Jon.

Tricky. It's been "Noda Time" in general, following "Joda Time" - although I see that in the Joda Time docs that's sometimes hyphenated. I think I'm happier keeping it as two words - the reason the "T" is capitalized in the namespace is precisely because it is two words. I could probably be persuaded otherwise though.

This leads me to another interesting problem - currently we have http://noda-time.googlecode.com and http://noda-time.blogspot.com - but we were proposing buying nodatime.org or nodatime.com, not noda-time.org. Is that inconsistency a problem? Hopefully not, but it's worth thinking about.

Jon

[Jon Skeet]

(Just responding to the last bit, as the design discussion seems to be going well on its own :)

On 3 June 2013 20:29, Nathan Palmer <nat...@nathanpalmer.com> wrote:

Yes, this is purely placeholder. To be honest one of the short comings to the existing documentation is figuring out exactly "how" you use NodaTime.

The user guide tries to address this - but obviously it could always be better,

 

We need to come up several "quick start" examples that demonstrate how you would commonly use it within an application.

That would be good - but I'm also somewhat nervous about it. You see, the exact way that you'll use Noda Time depends on your exact problem. I can imagine people seeing something similar to what they want, and then using that as the basis of their code instead of finding the more direct route that may be available. I'm not saying we shouldn't have quick start examples - just that we need to be careful with them.

Also, it's probably worth bearing in mind that in some cases the Noda Time code can be more long-winded than the equivalent BCL code, simply because it's more precise. The equivalent of DateTime.Now is relatively painful, for example - precisely because DateTime.Now is "bad" in two different ways (quietly using the system time zone, and using a static hard-to-test property).

If anyone would like to try to think of some sample cases we should cover, I'd be happy to work up the code - I think I may be too close to the code to have a good sense of what the most common examples would really do.

 

This page needs to pass the 12 second test when a user pulls it up and see's the example and immediately will recognize that it provides a benefit (within 12 seconds.) If we have enough good examples I could see expanding this section out to include 4 simple usage examples.

I love the aim, but I think it's a tall order. Understanding the benefits of Noda Time involves understanding that date/time is probably a trickier business than you've previously thought. Persuading a new user of that in 12 seconds could be tricky. But I'm up for the challenge... to my mind the primary benefits of Noda Time are:

• Separating out the different concepts (LocalDateTime, LocalDate, LocalTime, Instant etc)
• Reducing surprise - no use of default time zones, and only using thread-default culture either explicitly or when using the BCL-compatible ToString methods
• Encouraging testability (injectable clocks and time zone providers etc)
• TZDB support

Which of those resonate most strongly with others? What did I miss? 

It might be useful as well to highlight a proper way to work with timezone's since that seems like the focus of Jon's original "what's wrong with DateTime" post (the ambiguity of it.) I think I'd be looking for someone here on the list to step forward with some ideas though as I haven't written code directly against NodaTime before (just reviewed code that contained it.)

Your mention of the DateTime post reminds me of something else I'd like to talk about in relation to the website - what we do about our dynamic content. We have three main sources of that content:

• API documentation
• User guide
• Blog posts

I'd really love it if we could host all of this on the same website. Whether we also continue to host it elsewhere is up for grabs, although I'm broadly in favour of doing so. (I'm happy to keep using Blogger as the place people can comment on blog posts, for example.)

I'm not sure how we style both the API docs and the user guide to fit in with the rest of the site - or if it even makes sense to do so for the API docs. (The user guide should be much simpler.) Does anyone have any good examples of other sites doing this well? (In my experience finding API docs for .NET Open Source projects is often a futile effort, which is a shame.)

Great to see progress on this - thanks again, Nathan!

Jon

[Matt Johnson]

RavenDB does a reasonably good job in how they present their documentation  (www.ravendb.net) - although it's probably not as well-maintained as it could be, but the approach seems solid.

I'm not sure how I feel about mixing blog posts into there. I've always seen that separate.  Perhaps more "Knowledge Base" style posts would cover common "how-to" scenarios that augment the documentation?  Of course, the biggest challenge is writing them, but that's where contributors can help.  :)

IMHO, the order of importance of features is:

1) TZDB support - although there are other libraries if that's all you want:

    - TZ4Net (http://www.babiej.demon.nl/Tz4Net/main.htm) which is maintained

    - ZoneInfo (http://zoneinfo.codeplex.com/) which is not.

  But both use DateTime under the hood, which leads to the next point

2) Separation of Concerns - I can explain TZDB vs Windows Time Zones easily,  but it's very difficult to explain to a novice why DateTime is different than LocalDateTime.  This will be the biggest challenge for the 12 second test.

3) Reducing Surprises - I think once you get past point 2, this should be relatively straightforward.  Perhaps it's best to illustrate some of the surprises that people commonly encounter with DateTime that are cleanly avoided with Noda Time.  (For example, I just answered a question today on SO (http://stackoverflow.com/q/16916840/634824) about the hidden fourth kind, and having to parse with DateTimeStyles.RoundTripKind to honor the "Z" in an ISO string.)   Maybe a chart of BCL "gotchas", and a corresponding illustration of how that just doesn't happen with Noda Time.

4) Testability - while important, I think others have found workarounds that are acceptable (such as https://github.com/ravendb/ravendb/blob/master/Raven.Abstractions/SystemTime.cs).   I think it's worth mentioning, but I don't think this by itself will attract very many developers.

What did you miss?  I'd say CLDR support - at least in regards to TZDB / Windows Zone translations.  Until Microsoft gets off their high-horse and puts the TZDB into Windows, we'll always need this.  Maybe they will eventually listen and cave in for Windows 9 or 10.  But who really knows.

[Nathan Palmer]

I think we have some decent progress on what the "highlights" should be. The key for the front page, and why I brought up the 12 second test, is to give the developer enough information to entice them to look further. So we'll want to keep it simple and I think we can put together a basic example of what's been mentioned so far. May not be able to give a good enough description on how to choose a LocalDateTime vs ZonedDateTime, but we could give enough info to tell them why they need that.

I think the user guide should be pulled into the homepage and for now keep the blog and api separate. I think the API integration would be the next thing to get integrated if we were going to do it but that would require some templating on whatever tool is generating it today (which I'm not sure what it is.) As far as knowledge base that I'd assume could stay as stackoverflow questions and answers.

I'll take a look at this tonight and put together another update with a simple user guide integrated in it.

Nathan

[Jon Skeet]

One thing to bear in mind is how this is updated. I chatted with Malcolm about this earlier on, and hopefully he'll send out a more detailed mail, but...

• Unless we have any reason not to, it would be handy to have the web site in source control, with "push to publish". (We can get the hosting site to poll if we can't get a push notification.) So we'd have something like a /www root in Mercurial. As far as I can see, we don't need any dynamic content at all, at the moment.
• It would be nice to have versioned directories for the user guide and API when we get there, e.g. /www/development/userguide, /www/development/api, /www/1.0/userguide etc

Updating the user guide would just be a matter of going through the normal "build docs" process - we may well want to have different templates for downloadable docs than online docs, but that's all.

Jon

[Nathan Palmer]

The way I have it currently setup is through Jekyll (http://jekyllrb.com/) which generates a static site after the build is done. The user guide documentation would be in simple markdown files in a directory and any new file that shows up there would end up being part of the site. I think it will be pretty easy to update via source control. I have my local version in source control just haven't pushed it anywhere yet. Now GitHub supports Jekyll as a first-class citizen which means when you push changes it goes live, however if it's hosted somewhere else then it's a pretty simple "jekyll build" to get all the HTML and it could be setup on a build server if necessary. (ruby required)

I too believe that it should be easy to update the content, for anybody. Having the content in source controlled text files makes it easily approachable for a developer. However, let me know if you have any thoughts/changes on my current setup.

Also, it should be pretty easy to do versioned directories for the user guide. All it would really require is to layout the directory that way and point the main url at whatever the "live" version is. If you wanted to create a 1.1 then you duplicate 1.0 and start making the necessary changes. Then swap the main URL when it's ready. Jekyll just makes it easy to automate the templating, nav, sidebar for user guide, etc but ultimately ends up being a static site.

Nathan

[Jon Skeet]

On 4 June 2013 19:20, Nathan Palmer <em...@nathanpalmer.com> wrote:

The way I have it currently setup is through Jekyll (http://jekyllrb.com/) which generates a static site after the build is done. The user guide documentation would be in simple markdown files in a directory and any new file that shows up there would end up being part of the site. I think it will be pretty easy to update via source control. I have my local version in source control just haven't pushed it anywhere yet. Now GitHub supports Jekyll as a first-class citizen which means when you push changes it goes live, however if it's hosted somewhere else then it's a pretty simple "jekyll build" to get all the HTML and it could be setup on a build server if necessary. (ruby required)

I too believe that it should be easy to update the content, for anybody. Having the content in source controlled text files makes it easily approachable for a developer. However, let me know if you have any thoughts/changes on my current setup.

How big/ugly is the generated site? I'd be happy enough for both the source and generated form to be in source control if that makes things easier... but hosting the build process shouldn't be too bad either. (I may be able to reuse the csharpindepth.com server - I'll check.)

Also, it should be pretty easy to do versioned directories for the user guide. All it would really require is to layout the directory that way and point the main url at whatever the "live" version is. If you wanted to create a 1.1 then you duplicate 1.0 and start making the necessary changes. Then swap the main URL when it's ready. Jekyll just makes it easy to automate the templating, nav, sidebar for user guide, etc but ultimately ends up being a static site.

I wasn't going to version the whole site - just the docs directories, which would be built from the docs from that branch. We could potentially make the build process just fetch multiple branches and assemble them appropriately. We could have a simple mapping table of branches to fetch etc.

Jon

[Nathan Palmer]

The generated site is pretty simple at this point and it looks very similar to the "ungenerated" site except all the markdown (md) files are converted into html and all variables/loops/includes in the templates are pulled into the file itself. We're dealing with about 4 megs of data at this point with both ungenerated and generated. All generated files go under the _site directory. I can push it up somewhere tonight/tomorrow if you want to have a look.

The "ungenerated" would roughly look like this

userguide/

  - 1.0/

    - index.md

    - why-does-this-project-exist.md

    - choosing-between-the-core-types.md

css/

fonts/

img/

js/

index.html

robots.txt

We could look at pulling the user guide dynamically via the build as well as you mentioned. Could either branch the entire site code.. or could subrepo/submodule one that contained just the documentation. Are you planning on keeping simultaneous version of the documentation online at the same time? (i.e. version 1.0 and 1.1?) Build would need to just pull from the branch/tag for each revision into a specific directory and then run jekyll to generate it.

I also have servers in a data center if the hosting w/ csharpindepth.com doesn't work out.

Nathan

[Jon Skeet]

On 4 June 2013 19:48, Nathan Palmer <em...@nathanpalmer.com> wrote:

The generated site is pretty simple at this point and it looks very similar to the "ungenerated" site except all the markdown (md) files are converted into html and all variables/loops/includes in the templates are pulled into the file itself. We're dealing with about 4 megs of data at this point with both ungenerated and generated. All generated files go under the _site directory. I can push it up somewhere tonight/tomorrow if you want to have a look.

I'm unlikely to get time to look at it properly in the very near future, but it sounds good to me.

 

The "ungenerated" would roughly look like this

userguide/

  - 1.0/

    - index.md

    - why-does-this-project-exist.md

    - choosing-between-the-core-types.md

Right - those bits could be pulled in from the existing locations, I think.

 

css/

fonts/

img/

js/

index.html

robots.txt

And all of this under /www

We could look at pulling the user guide dynamically via the build as well as you mentioned. Could either branch the entire site code.. or could subrepo/submodule one that contained just the documentation. Are you planning on keeping simultaneous version of the documentation online at the same time? (i.e. version 1.0 and 1.1?)

Yes. The plan is that someone using Noda Time 1.1 can still look at the relevant docs for them, even when we've released 2.0 etc. We only need the latest of each appropriate branch though, I think.

Build would need to just pull from the branch/tag for each revision into a specific directory and then run jekyll to generate it.

Right - or for the userguide we can use the existing build, keeping Jekyll basically for the web site. Or maybe change the user guide generation process to use Jekyll entirely and ditch my custom code :)

 

I also have servers in a data center if the hosting w/ csharpindepth.com doesn't work out.

Looks like it should be fine, but let's see - it's definitely good to have backup optoins.

Jon

[Nathan Palmer]

Ok. I put together an easy way to do the user guide using markdown files. Essentially what we have talked about so you can have multiple version folders if necessary. What format is the userguide in now? I'd like to take it and convert it over so I have the full set of pages. I have converted several of them manually to get an idea on styling. I still have a few things I want to update on that though before showing.

Now for the front-page we need to nail down exactly what we want said assuming we'd like to expand on the small amount of information on the page now. From what you guys have discussed so far it sounds like we can together 4 simple sections. I took the feedback provided and came up with a list. Take a look at this and add/modify what you can. If there are any code snippet examples you could provide or point me at that would be great as well.

Reducing surprises

  * There are no default time zones

  * DateTime tries to be everything and makes too many assumptions. This leads to time consuming and difficult to identify problems.

  * Thread-default culture is explicit

Separation of concerns

  * Several data types available

  * LocalTime when you just need the time component

  * LocalDate for dates only

  * Instant to represent "ticks" similar to a unix timestamp

Multiple timezone providers

  * TZDB

  * Windows

  * Conversion to and from

  * Easily allow you to update the list

Testability

  * Encourages testability

  * Injectable clocks

  * Injectable timezone providers

Thanks,

Nathan Palmer

[Jon Skeet]

On 6 June 2013 01:33, Nathan Palmer <em...@nathanpalmer.com> wrote:

Ok. I put together an easy way to do the user guide using markdown files. Essentially what we have talked about so you can have multiple version folders if necessary. What format is the userguide in now? I'd like to take it and convert it over so I have the full set of pages. I have converted several of them manually to get an idea on styling. I still have a few things I want to update on that though before showing.

It's in Markdown using the Stack Overflow formatter, but with special handling for links to API documentation. See src/docs/userguide for the input and src/NodaTime.Tools.BuildMarkdownDocs for the processing code.

 

Now for the front-page we need to nail down exactly what we want said assuming we'd like to expand on the small amount of information on the page now. From what you guys have discussed so far it sounds like we can together 4 simple sections. I took the feedback provided and came up with a list. Take a look at this and add/modify what you can. If there are any code snippet examples you could provide or point me at that would be great as well.

Reducing surprises

  * There are no default time zones

  * DateTime tries to be everything and makes too many assumptions. This leads to time consuming and difficult to identify problems.

  * Thread-default culture is explicit

I think the first and the last points here could be grouped, potentially - and the key word here is "explicit". There's still the concept of a system-default time zone, but you need to ask for it explicitly.

The second point reminds me of another way I've put it before: Noda Time forces you to take a decision where you really ought to, but it makes it easy to take that decision. So not defaulting the time zone is one example of that, and another is the conversion from local date/time values to ones in a particular time zone: you have to specify a policy around ambiguous or invalid times, but it's easy to do so.

Separation of concerns

  * Several data types available

  * LocalTime when you just need the time component

  * LocalDate for dates only

  * Instant to represent "ticks" similar to a unix timestamp

Yup - and plenty of others. The problem is that we probably don't want to list all the relevant types here, as it would be overwhelming.

 

Multiple timezone providers

  * TZDB

  * Windows

  * Conversion to and from

  * Easily allow you to update the list

Testability

  * Encourages testability

  * Injectable clocks

  * Injectable timezone providers

Would your plan be to show all four at once? I've seen some sites use animation to highlight one benefit at a time. I'm not sure whether I like it or not, mind you...

Jon

[Jon Skeet]

Just thinking about the generation part again, I suspect the simplest approach may be to separate the site serving from the site generation. I don't know whether I announced before, but I now have a secondary CI system running at home - it's primarily for performance benchmarking (it runs a full benchmark each time it notices changes, and uploads the results to Azure) but it could easily run the site generation too. This is probably easier than doing it on the CodeBetter TeamCity installation, as we can install whatever we want on my box.

So then we'd just need somewhere to host the results, with a way of pushing from the build box to the web site. That can probably be done pretty much anywhere - ideally with an appropriate syncing framework to avoid transmitting the whole thing each time. I'll look into some options along those lines.

At that point, if we host all the docs including API documentation, we would probably stop putting the docs into source control at all, which would be very handy. We'd still want to include them in release binaries, but that's easy enough to do.

Any thoughts? Any sync recommendations?

Jon

[Nathan Palmer]

I agree on separation of Generation vs. Serving.

As far as sync recommendations I generally do 1 of 2 things but both largely depends on your build source and deploy destinations.

• Put the generated site in source control (generates a small diff, but you'll need a way to "invoke" the update) You can also host a mercurial/git repository on the web server and just push the content to that IP/url.
• Run ROBOCOPY against source and destination (requires servers to be on the same network -- even if WAN)

Nathan

[Jon Skeet]

I'm actually working on a version of the first option right now:

• I've registed nodatime.org
• I've created an empty Azure web site
• I've configured DNS to point one to the other
• I've told the web site that I'm going to push from a local git repository
• I'm now installing GitHub for Windows on Bagpuss

So the plan is that at the end of the CI build, I regenerate the contents of the web site locally, and just do a git push to Azure. That should Just Work.

Jon

[Jon Skeet]

Update to this: I now have a fairly hacky build on Bagpuss which publishes to nodatime.org.

Next steps:

• Learn how to build Nathan's website myself, then reproduce on Bagpass
• Put the source code for the website into source control
• Automate the building of website + userguide + API docs
• Work out the best way to "clean" the website folder before updating it
• Party!

For the moment I probably won't add any specific support for old versions: I can fetch from Azure, add the appropriate docs, then push the changes. Pull again from Bagpuss to make sure we don't get merge conflicts, then we're good. I can look into automating that later.

While it would be great to have all of that done before NDC, I can't see that happening in reality - so I think the next best thing would be to just dump some content on there (whatever Nathan's latest and greatest is, basically :) and then iterate from there.

Sound good?

Jon

[Nathan Palmer]

Sounds good. Where do you want the site code? I have pushed it up to github in a temporary location so you can take a look as well as see the site in action. The full user guide has been pulled in and I labeled it 1.1.0 but looking at the content it seems to have 1.2 updates in it. 

• GitHub: https://github.com/nathanpalmer/nodatime
• Viewable Url: http://nathanpalmer.github.io/nodatime/

I'm preprocessing the links the same way you had in the project so that noda-time/noda-tm as well as issues link to the correct place. You'll see this in userguide.rb. However I'm trying to keep custom code here to a minimum as jekyll is being used as a generator and not as a framework for building this.

The api links right now aren't working until we decide where those are going to go. You could easily host the api on the website.. Might actually make sense now that I think about it by putting the compiled api in the website directory. The path for the api can easily be modified in userguide.rb as it's a class variable.

If you want to pull this down as try generating it follow these steps.

• Install Ruby (I have 1.9.2 installed I believe)
• Install Jekyll (gem install jekyll)
• Install Redcarpet (gem install redcarpet) -- this is close to Stack Overflow markdown

Then in the checkout directory just run

• jekyll build

And you should get the html files in the _site directory. If you have any questions let me know. There are additional things that can be done to the site and I can keep moving on it but I wanted to make sure this was out as it sounded like you wanted to get it done prior to NDC (which is coming up soon I believe.)

Nathan Palmer

[Jon Skeet]

Woot - thanks for that. I've installed Ruby and Jekyll already (Ruby 2.0.something, but should be okay)... will try to do the build on my desktop machine first, then put the source of it into Hg, and then go for building it on the CI machine.

Once we've got the general structure into the main repository, you can make changes there instead :) I'm sure I'll have a list of feature requests, mind you... (I had some interesting ideas about dynamic things we could do by running Noda Time on the web site itself - things like recipes where the code shown on the screen was what executed on the server and showed the resutls, and a "text parsing playground" for example. That can all come later!)

Jon

[Nathan Palmer]

Sounds awesome! Once you have some examples of that dynamic content let me know, could be fun to put together.

FYI, I went ahead and added the developer guide and api to the site as well. If you load it up now it'll show that. Also the links to the API were partially wrong (as I didn't fully read your TranslateUrl method) so those are fixed now.

Nathan Palmer

[Jon Skeet]

Check out nodatime.org now :)

Next step will be working out where to put the site code within the Hg repository, then making it part of the actual build.

(I may just tweak the page very slightly in the meantime - I'd rather not claim to be industry standard just yet...)

Jon

[Matt Johnson]

I love it!  Great work everyone!

[Jon Skeet]

Actually, possibly the next thing to work out is how to merge Malcolm's changes to the user guide for navigation with Nathan's changes to support Jekyll. See the latest user guide to see what the navigation looks like.

I'm happy with the idea of building the user guide and the developer guide with Jekyll too, but I would like to keep the user guide downloadable separately from the rest of the web site, ideally with navigation. Is that likely to be an issue with the way things are laid out for the site? I realize that keeping the two objectives in parallel could be tricky. I'd like us to have just one tool for building the guide in the long run, even if we need to invoke it twice with different arguments (one for the site, one for the isolated version).

I've copied over the site from Nathan's Git repo into our Hg one, which is where work should be done now. (Nathan, I'll give you commit access - what address would you like me to add?)

I've included the 1.1 user guide and developer guide, but removed the API for the moment - partly because it's a huge thing to include when we want to get rid of it from source control entirely :) I've removed the API link from the top nav bar, but made the links in the user guide go to the 1.1 docs on Google code. This is obviously only a temporary measure, but it felt like a way of moving forward a bit.

Jon

[Steinar Dragsnes]

Hi!

 

This looks really great guys. Looks like it’s time to pull down Noda again and this time maybe it will be included in production code, we will see!

 

Great work.

 

Steinar.

[Nathan Palmer]

Look good Jon! Nice to see it live.

We should be able to build a static version of the userguide by replacing the userguide.html template and running the jekyll build again. We'd probably need to build in some relationship between documents in the front-matter (header) of the .md files themselves or just assume based on the order the nav is built in. Of course that's mostly arbitrary at the moment unless you add the "weight" to the top.

(Also you can add my snowpalmer address to the repo - @gmail of course)

Nathan Palmer

[Malcolm Rowe]

On 8 June 2013 09:22, Jon Skeet <sk...@pobox.com> wrote:

Check out nodatime.org now :)

Looks great.

Couple of comments:

- The user guide at http://nodatime.org/userguide/1.1.0/ is clearly the 1.2.x user guide :-).

- Are we ditching the download links?  We _could_ (it would certainly simplify distribution), but I'd like it to be a deliberate choice to depend upon NuGet, if so. (And we also don't have a source package available via NuGet, so we'd probably need to remedy that.)  fwiw, we currently get about 20-25% of downloads directly, split evenly between the source and binary archives (it may be some of source downloads are from people who already downloaded the binary via NuGet).

- The persistent TOC on the user guide is quite nice vs the next/previous links I put in place, though it loses the ability to easily move through the guide without repeatedly remembering where you are. Also, reading the guide linearly through second-level topics (i.e. the pattern-specific pages) is now quite hard, as they're not on the TOC at all.

- The mobile rendering of at least the front page could use some work (the user guide is fine on mobile, at least, but the front page kinda falls apart).

- On the front page, we seem to have the summary (mission?) split between two lines. The Google Code page uses "Joda Time is the industry standard date and time handling library for Java. Noda Time is an idiomatic port to the .NET platform", which I've always thought is a pretty good summary, while the new page has both "A better date and time API for .NET" (reasonable), and "Noda Time aims to create a library which is powerful and easy to use correctly" (which seems to almost be a non sequitur).  Was the latter supposed to be read as a caption for the image instead?

- Is there any way we could pull more of the content up from the bottom of the front page? On my laptop (a fairly-average MBP), the "More Info" text is right at the bottom of the page, so most of the interesting text is below-the-fold. Perhaps consider moving the large title to the left of the image, and ditching the text that's currently there? That would pull the Community/Documentation/Contributing sections entirely onto the page.

- nit: copyright should probably be the same text we use elsewhere (i.e. "The Noda Time Authors").

- nit: we can probably do with a little improvement on the guides' renderings: for example, the body text is serif, but list items are sans serif - and the font choice makes it obvious that we don't have an auto-smart-quotes conversion a la SmartyPants; can we do something like that?

But overall, I think this is a substantial improvement; well done!

Regards,

Malcolm

[Nathan Palmer]

Excellent feedback Malcolm! This is just what I needed. See below, inline, for comments.

On Sat, Jun 8, 2013 at 3:38 PM, Malcolm Rowe <malcol...@gmail.com> wrote:

On 8 June 2013 09:22, Jon Skeet <sk...@pobox.com> wrote:

Check out nodatime.org now :)

Looks great.

Couple of comments:

- The user guide at http://nodatime.org/userguide/1.1.0/ is clearly the 1.2.x user guide :-).

You are correct. I had a feel it was the 1.2.0 version. I have swapped it out now with 1.1.0 and copied the 1.2.0 guide into the 1.2.0 folder. We are now carrying duplicate copies though so I'd suggest we remove the ones outside of the www/ folder.

 

- Are we ditching the download links?  We _could_ (it would certainly simplify distribution), but I'd like it to be a deliberate choice to depend upon NuGet, if so. (And we also don't have a source package available via NuGet, so we'd probably need to remedy that.)  fwiw, we currently get about 20-25% of downloads directly, split evenly between the source and binary archives (it may be some of source downloads are from people who already downloaded the binary via NuGet).

I'm certainly in favor of Nuget but I'll let others stand in here. Binary downloads are nice from time to time as well. I've added it to the site and we can decide whether to keep it or ditch it.

 

- The persistent TOC on the user guide is quite nice vs the next/previous links I put in place, though it loses the ability to easily move through the guide without repeatedly remembering where you are. Also, reading the guide linearly through second-level topics (i.e. the pattern-specific pages) is now quite hard, as they're not on the TOC at all.

Totally agree here. Also it was a bit out of order. I have fixed both. We now have ordered documents (and a new text section) along with a "next" link that takes you to the next document to read.

 

- The mobile rendering of at least the front page could use some work (the user guide is fine on mobile, at least, but the front page kinda falls apart).

Since this was thrown together pretty quick I'm not surprised the front-page isn't quite working on mobile. I did use a mobile framework to build this out but I'm sure a bit more work will need to be done here to get it all working correctly.

 

- On the front page, we seem to have the summary (mission?) split between two lines. The Google Code page uses "Joda Time is the industry standard date and time handling library for Java. Noda Time is an idiomatic port to the .NET platform", which I've always thought is a pretty good summary, while the new page has both "A better date and time API for .NET" (reasonable), and "Noda Time aims to create a library which is powerful and easy to use correctly" (which seems to almost be a non sequitur).  Was the latter supposed to be read as a caption for the image instead?

Both are aimed to be bold statements about the product itself. I'd like to keep them short and simple but surely not opposed to changing the text.

 

- Is there any way we could pull more of the content up from the bottom of the front page? On my laptop (a fairly-average MBP), the "More Info" text is right at the bottom of the page, so most of the interesting text is below-the-fold. Perhaps consider moving the large title to the left of the image, and ditching the text that's currently there? That would pull the Community/Documentation/Contributing sections entirely onto the page.

This is a personal preference. I like to show code first and some bold statements about the product above the fold in order to entice the user to read more.

 

- nit: copyright should probably be the same text we use elsewhere (i.e. "The Noda Time Authors").

Sounds reasonable.

 

- nit: we can probably do with a little improvement on the guides' renderings: for example, the body text is serif, but list items are sans serif - and the font choice makes it obvious that we don't have an auto-smart-quotes conversion a la SmartyPants; can we do something like that?

I'm pretty sure we can do SmartyPants or something like it (and certainly fix the serif/san issue.) I'll look into it.

 

But overall, I think this is a substantial improvement; well done!

Good to here! 

 

Regards,

Malcolm

[Nathan Palmer]

I just pushed some more website changes including optimizations for the mobile and ipad experience. Also, since my previous push included the real 1.1 docs (versus the 1.2 docs) we should try to get this pushed live.

Secondarily it seems the font issue Malcolm mentioned (san-serif/serif) is because the fonts aren't loading properly.

Not sure whether the files are actually missing from the server or if IIS (or whatever) is just not serving them.

Nathan Palmer

[Jon Skeet]

Sorry for the delayed response - I've been away for the weekend. I'll see what I can do either tonight or tomorrow. I still need to take a closer look at the differences in docs, and work out a plan for generating them once in the future. (I really like the idea of killing my custom C# project if possible :)

Jon

[Jon Skeet]

Okay, new web site deployed and the fonts are sorted. We need a web.config file in the root directory with this content:

<configuration>

  <system.webServer>

     <staticContent>

        <!-- <mimeMap fileExtension=".eot" mimeType="application/vnd.ms-fontobject" /> -->

        <mimeMap fileExtension=".woff" mimeType="application/font-woff" />

        <mimeMap fileExtension=".otf" mimeType="application/x-font-opentype" />

     </staticContent>

  </system.webServer>

</configuration>

(We may want to change the .eot mime mapping too, but it's already defined as *something*, so it is being served.)

I haven't looked into what needs to happen in order to make that just appear in the _site directory on build - I wanted to concentrate on getting it working live first :)

Also, the 1.2.0 directory for the user guide should really be "dev" instead (or something like that) - the idea being that a numbered directory should refer to a release, and be stable in itself. But we can do all of that when we've worked out exactly how all of this is going to be managed. Baby steps :)

Jon

[Matt Johnson]

The only thing I don't love about the new site is the text on the home page:

"Noda Time aims to create a library which is powerful and easy to use correctly."

Isn't there something more intelligent we can say here?  I'm racking my brain for suggestions but am coming up empty.  Perhaps some rotating testimonials?

Another thing that seems notably absent - there's no contributors list.  Jon, having you as the primary author adds tremendous credibility to this library.  Perhaps instead of saying "© The Noda Time Authors", could it say "© Jon Skeet and Contributors" instead?

[Jon Skeet]

On 24 June 2013 21:56, Matt Johnson <mj1...@hotmail.com> wrote:

The only thing I don't love about the new site is the text on the home page:

"Noda Time aims to create a library which is powerful and easy to use correctly."

Isn't there something more intelligent we can say here?  I'm racking my brain for suggestions but am coming up empty.  Perhaps some rotating testimonials?

I don't think we're at the testimonials stage yet - but yes, we can definitely do better than that. I'll see what I can do in the morning. This is my least part of the site at the moment.

Another thing that seems notably absent - there's no contributors list.  Jon, having you as the primary author adds tremendous credibility to this library.  Perhaps instead of saying "© The Noda Time Authors", could it say "© Jon Skeet and Contributors" instead?

Hmm. I'm in two minds here. On the one hand, I definitely don't want this to be an ego project. On the other hand, I can see that the somewhat misguided opinion of me which appears to be common could be quite useful to aid adoption. Will ponder this.

Jon

 

[Jon Skeet]

Least favourite part of the site at the moment. Memo to self: don't type when tired.

[Jon Skeet]

I've updated it to:

Noda Time is an alternative date and time API for .NET. It helps you to think about your data more clearly, and express operations on that data more precisely.

I'll regenerate the web site when I get a chance, as well as looking at putting the web.config in the www directory.

Jon

 

[Nathan Palmer]

Anything you throw in the /www/ directory should get copied into _site so you should be safe putting the Web.config directly in there. Throw it in next time right before you generate and see if it picks it up. If it doesn't let me know and I can take a closer look. I'm pretty sure though that it takes any file and copies it to _site. It just has a whitelist of extensions that it "converts."

[Jon Skeet]

Fabulous, thanks.

I'm now trying a run with it entirely automated - a Mercurial checkin will trigger a build (including benchmarks, so it takes half an hour or so) followed by a web site build and push. We'll see whether or not it works :)

Jon

[Jon Skeet]

And... it works. So any changes to www should be picked up automatically. I haven't checked how the user guide is now pulled in, but I'll look at that later...

Jon