2

I'm currently developing a WinForm application. In order to inform the client about the improvements and corrections made during the last version, I would like to manage and display a changelog.

I mostly found existing changelog on website (the term changelog is pretty used) or explanation on how to manage the release numbers, which I don't care.

So, these are my questions:

  1. How do I manage a changelog (using XML, pure text in the app, etc.) in a desktop application?
  2. How do I present it to the user (external website, inside the winform application)?
gnat
  • 21,442
  • 29
  • 112
  • 288
Nate B.
  • 131
  • 5
  • GNU software have `ChangeLog` files with a well defined format (known to `emacs` editor). – Basile Starynkevitch Aug 18 '14 at 09:34
  • [Sharing your research helps everyone](http://meta.programmers.stackexchange.com/questions/6559/why-is-research-important). Tell us what you've tried and why it didn’t meet your needs. This demonstrates that you’ve taken the time to try to help yourself, it saves us from reiterating obvious answers, and most of all it helps you get a more specific and relevant answer. Also see [ask] – gnat Aug 18 '14 at 09:38
  • I updated the answer. I mostly find existing changelog or topics about release numbers maangement. And that's not my point. I'm not asking for code or any implementation, but advice on the way to deal with this. Does someone already used some in a desktop app ? – Nate B. Aug 18 '14 at 09:57
  • And I completely agree with you, research and knowledge sharing is important, and I've already searched few times on the subject. Meanwhile, if a relevant answer is found, I'll post it here. – Nate B. Aug 18 '14 at 09:58
  • 1
    I edited your question to remove references to "best practices" or "what is the best way to do X?" which are [subjective](http://meta.programmers.stackexchange.com/questions/6483/why-was-my-question-closed-or-down-voted/6491#6491) and may result in a question being closed. This question is still borderline, though. –  Aug 18 '14 at 18:11

1 Answers1

1

This is primarily a user interface question. Therefore: (1) You might want to check ux.stackexchange.com. (2) The correct answer to most, "What's the best UI?" questions is, "Do a test (such as a hallway usability test) and find out for yourself."

With that out of the way...

"Informing the client about the improvements and corrections made during the last version" can take a few different forms:

  1. "What's New", presented as end-user documentation (not programmer's perspective ocumentation) on things the user needs to know to help them better use the software.
  2. "What's New", presented as more of a marketing document, giving a list of reasons to upgrade or renew or whatever
  3. A changelog - a detailed list of every potentially user-visible change, commonly one change per line

It sounds like you're interested in a changelog, but don't neglect "What's New" documentation either.

How to manage your changelog? However you want to, really. Users won't care about the format, so do whatever format's easiest for you: auto-generated text from Git's short messages, XML, HTML, Markdown that you convert to HTML, whatever. I personally like HTML (or Markdown to HTML), because it's easy to work with and can be displayed by a variety of tools.

How to display it? Whatever presents a good UI and is easiest. I like a web browser, since the browser's UI probably gets a lot more attention than you can devote to your WinForms app, and if you host the changelog on your website and point customers to it, you can use analytics, fix typos, etc.

Whatever you do, keep in mind that, as David Platt writes, "Users don’t care about your program in and of itself." A detailed one-change-per-line changelog is likely of interest to very few users, and trying to get them to read one if all they want to do is fire up the app and get work done will likely do no good. A "What's New" guided tour or tip of the day, as long as it's not obnoxious and can be easily deferred until the customer wants to take the time to go through it, takes more work to implement but should produce better results.

Josh Kelley
  • 10,991
  • 7
  • 38
  • 50
  • Thank you for your answer, that's pretty much the kind of answer I was looking for (some experience feedback). I tag this as an answer. – Nate B. Aug 19 '14 at 06:25