As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
What are release notes for and who reads them? Should/could they be automated by just spitting out bug fixes for the current release, or do they warrant careful human editing?
So, anybody with a link to best practices(reasoning behind) in regards to software release notes?
Bugfixes and added features. Users will read them to determine if they should go to the trouble of installing an incremental upgrade, or wait until the next release because this one doesn't add any features they need or fix any bugs in features that they were using.
I'd say they at least require a human to read through them and make sure that each note is useful. It depends how good the comments on your bug fixes are.
Release notes are also important to your testing organization (if you have one), so that they know what's changed in the release and needs testing.
This really depends on who your application is built for and your organizations goals. However, I tend to believe that release notes need to be a concise listing of important key additions, enhancements, or fixes that are included in the particular release.
Sometimes a simple dump of the bug tracking system information is enough, other times, I find that they need to be refined.
The key is that typically Release Notes are believed to be the "Hey look at what we did" type listing of changes.
Our release notes are human created instead of machine created. The cover three main topics.
What is included in the releases
(list of files)
How to install it
What changed since the last version
(especially if the changes are not in
the manual yet).
items 1 and 2 don't chnage much from version to version, but they need to be reviewed. Item 3 takes the most work.
Release notes are also very important in production environment.
They help answering the age-old question:
What the heck is currently running into production ?
Or the more refined question: does this bug has actually been fixed in this release ?
I habitually read release notes. I tend to want a full comprehensive list of feature changes ( or as good as plausible ) in order to greater empower my utilization of the new product.
I want to see when certain critical bugs, or critical security issues are solved.
Release notes and READMEs can be really important if your customer has to take special action in addition to normal procedures in order to upgrade. It also be useful to warn customers/users of any db upgrades that can automatically happen as a result of installing a newer patch. The way I see it, Release Notes and READMEs should be written for the System Administrator audience. So include the kinds of things they would want to know about: summaries of important changes, how to install, known bugs, anything your software might do that would make someone pull their hair out, etc.
Release note depend of your organization.
I can talk for my organization. We use release note in PDF format and every time we publish a clickonce or a backend version. We send to office manager the Release note. This is a document used by the top administrator of the business (not only IT). This document is a way for them to know what is going on. What have changed, new features that are now in production, bugs fixed, and other thing that they might want to explain to their user.
This is a document that can be between 3 to 4 pages, describing the job that has been done in this version with brief words.
This is of course highly dependent on the type of application/service/whatnot,
but I've found that reading the release notes of my favorite developing tools etc..
often make me stumble upon nice, interesting or even killer features that I'd probably miss if I did'nt at least skim the notes.....well, perhaps not killer, but you get my drift ;-)
As most computer power users(now what kind of expression is that...)
I never bother much with ordinary documentation, so this gives me
that little something extra something besides clicking, hovering and faq'ing...
Release notes are for testers and users to know what's new/changed. Additionally, release notes can be used as supporting documentation when billing a new "version" of a software for client that you are building for them. v1.31 seems a lot easier to relate and drill into.
Rather than compile both lists manually, if you can use your release notes to do that for you it's great.
Related
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 11 years ago.
I want to program with a friend (or a couple) out of the same dropbox folder for a project. I want to put all the assets in the same folder, including config and db files. What I really want to know, is why this might be a bad idea.
I can already think of a bunch of positives:
Quickly sync work. As in, almost instant sync. Dropbox, I've noticed, really is that fast that it is almost like working local.
Program multiple parts at the same time
Dropbox is fast enough to allow one person to add a method, and then another person ad theirs a moment after
Eclipse or Gedit both check for changes in the files so we won't accidentally end up with a conflict.
This isn't a substitute for proper source control and versioning, which we would still use Git for. Dropbox does have 30-day versioning, but for obvious reasons, it is no substitute.
I think this is especially powerful in the beginning when this are changing so fast that every team member having the exact same copy of everything is very important. This is a Rails apps if that matters.
Don't use Dropbox for that, because you'll be on the phone/IM/whatever trying to figure out who is going to edit a particular file (no concurrency AND no checking out!). Use a concurrent versioning system like GIT or Mercurial. There are tons of other advantages. On the downside for Dropbox, you will end up with "conflicted files" all around, which you won't know what to do with much.
The other advantages to a real version control system are well-known. Here's a list from some random blog:
File space.
Let’s say your code
changes 10% each week. Under the
“folder backup” method, each week
you’re saving 100% of the code. Using
a proper VCS, you’re only saving 10%
of your code. I know hard drive space
is cheap, but it’s not free and I
never seem to have enough.
History.
The key to VCS, in my opinion, is
being able to document your changes in
more granular level than a file called
“Changelog.txt” that might not get
changed whenever you work on your
code.
Bug-location:
Let’s say you find
a bug in a method. You search the
history for that file and let the VCS
runs the diffs for you.
Complete
freedom to change code.
You don’t have
to worry about breaking something, or
removing possibly useful code. Before
I moved to VCS, I used to comment out
old code liberally but keep it ‘cos I
might need it. This quickly becomes a
PITA.
If you use git, there are several providers for free or cheap online repo.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
I want to be able to choose the right branching strategy for most thinkable situations and organizations. So I'm looking for a extensive list of positive and negative effects of extending the use of code repository branches in a development organization.
Please only post one pro or one con in each post, so that the voting system can help rank the feedback somewhat.
Pro: By keeping latest deployed version in trunk, small fixes can be rolled out quickly without extensive testing of the latest development version.
Pro: Developers can work more freely in tighter iterations without stepping on eachother's feet.
Pro: if you have many branches you'll be pushed to adopt a modern DVCS (my experience is with Mercurial but I hear git or Bazaar are also good) rather than stay with a traditional centralized system (like, say, svn).
Pro: Branches can be used to facilitate 'what-if' scenario's in trying out new code. At the end a decision can be made to merge the new feature or to abandon it.
Con: Having too many branches in the air at the same time and you start forgetting where things where commited, where changes have been made etc.
Con (and it can be a big one): Merging back at a point in the future. The longer the duration and the greater the deviation of code base, the harder your life will be. My advice: think very carefully about branching and ensure you only do it when necessary and consider the effort involved in merging at a later date should it be required.
Con: Merge nightmare.
Con: Greater learning threshold for junior developers.
Pro: Each update is independant from the others, so work can be parallelized.
Con: someone has to manage the branch(es) and keep on top of things. In most teams this falls by the way-side.
Pro: Greater flexibility in diverging code for the purpose of simultaneously developing on or supporting multiple streams of work.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
I was curious how often other software developers reevaluated their development environments and tools. I used to work at a large corporation with rigid toolsets that everyone hated, but could do nothing about. So nobody ever really updated their development environments because we couldn't in that environment.
Now that I'm in my own start-up I find I can spend endless time evaluating new tools and development environments, but that I really shouldn't and can't afford to. I've committed to spending 1 day a month looking at new development tools and trying them out to see if it is worth switching.
How often do you try out new IDE's, editors, bug tacking tools, debuggers? Or update to newer versions of your own?
It's an ongoing process, but I don't make major changes more often than every two years or so. A major change involves too much time, and the tradeoff isn't generally worth it. Major changes might be defined as changing the whole target or compiler architecture and toolchain for an existing project.
Note that major changes can occur between projects - a new project can settle on a completely different architecture and toolchain with no significant cost. But care should be taken not to go too bleeding edge here. An evaluation process is needed to prevent selection of a setup that will not support the project later as the project grows in complexity.
But for minor changes I simply upgrade my tools and environment as I find opportunity and reason to do so.
-Adam
For me, upgrades are event-driven, not timer-driven. I keep my ear to the ground for new tools (libraries, IDEs, CASE tools, etc) and evaluate them as they show up on my radar.
Working with Microsoft technologies, I move to the newest version if there's no compelling reason holding me back. With OSS, I use what I know unless there's something compelling pushing me forward.
IDE's. I tend to stick with one I know will grow, and support my language. In my dev environment it's vim. It is actively developed, and has many many scripts(kinda like plugins) as well as documentation for DIY. Also leaning an IDE takes time, and becoming good at it, using it efficiently takes more time.
Revision Control. I try to stay just below the bleeding edge. The benefits of new features are important. For example Subversion 1.4, only supported rudimentary merging. Subversion 1.5 has overhauled their merging system, and added new features.
Task and project management. I tend to do that only every couple of years, and only if there is a good perceived benefit. Otherwise I will continue to upgrade my current system to the current stable release every couple of months.
Libraries. They are a toss up. Since most everything I do does not end up in a shipped out product. I feel more free to upgrade often, but we tend to shy away from upgrading when backwards comparability is broken.
Hope my $0.02 was useful.
At work, we upgrade a tool when our version reaches end of support lifetime. We upgrade to the next-older version.
At home, I upgrade as soon as I can find a copy of the new thing free (i.e. some deals where attending 3 webcasts will send you a copy of vs2008 std edition, user groups, etc.).
I only update unless I'm really missing out on a certain piece of functionality, or realize that NOT using one tool instead of another leads to more tasks taking longer/being less efficient.
IDEs - This can be tricky but I have gone through a few different progressions over the years. Sometimes being on a project or a specific feature can trigger an upgrade. For example, someone implemented a feature using LINQ so what was an ASP.Net 2.0 project became a 3.5 project overnight. Other times, it is just what is currently in use. A point here is that a change can impact a whole team so it isn't a change to be made lightly.
Bug tracking tools - This is also in that land of centralized stuff that has to be carefully managed. Since this is a QA tool, I'd hope they have their own policies of how often to look for updates and when to install them as sometimes new features can be cool to get. The dev team equivalent would be when to update the wiki.
Version control - These are individually managed since most of us use Tortoise SVN so we each have a local client copy. So, the updates are done when someone wants to do it. I like to stay up to date as much as possible, personally.
OS - While part of this can be controlled on a department basis, there are enough different pieces to update that sometimes I'll run an update on my own. I'm not sure when we'll move to Windows 7 as I know we aren't going to Vista and I'd think at some point we'd get off XP as I've been on XP now for about 5 years as before that I was on Windows 2000 Professional for a few years and NT 4.0 before that.
PC - There is a policy that every 3 years we get new machines I believe. When I started where I am now, I was on a P4 box, so the upgrade to a dual-core box was very nice as well as a good RAM boost from 2 GB to 4 GB.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 9 years ago.
I need a tool for collecting feedback and new ideas inside our company regarding our internal IS product. The problem is the acceptance level for such a tool.
Most of our colleagues are not IT oriented, so a solution like BugZilla or Jira is way to complicated for them to use. You need to create an account, take care of a lot of parameters before submission, new ideas about new software doesn't really fit well in these tools, etc...
So, here are my requirements:
No login need, or optional.
Few fields to enter.
If possible a WYSIWYG editor for the main description field.
Web based or E-mail based (we use outlook internaly).
Free (as a beer).
Not too chaotic (a Wiki is not an option)
I've take a look at uservoice (of course), it's really a nice tool for experienced people, but too complex for my target users.
Is the feedback you are seeking possible to collect through a questionnaire? There are many free solutions that provide you with questionnaire forms very easy to use, and if none apply it is also something relatively easy to implement.
I also do not understand why a wiki will not be a good solution, but regarding the Outlook, you have the possibility of doing simple votes (approve/reject) (yes/no):
See: http://www.microsoft.com/atwork/worktogether/forms.mspx
If the barrier to actually use the tool should be minimal, then perhaps the best way to collect the feedback is to use an e-mail address. Everybody knows how to use the system, so there is practically no barrier. And the feedback that is provided has to be processed by developers / management anyway, in order to decide what concrete actions are going to be taken. The developers can then use whatever system suits them best in order to keep track of bugs, immediately required functionality, nice-to-have features that can be implemented later, etc.
Some "defect tracking tools" handle this.
Don't vote down because of "defect tracking". Some of the tools are enterprise and handle incidents, requents, requirements, etc. And, you can go to one place for bugs and enhancement requests.
Microsoft's Exchange server has support for Public Folders, email lists/groups. This may be an easy introduction to collaboration for your environment, using tools that are familiar. From the Microsoft Help on Public Folders:
Public folders are an easy and
effective way to collect, organize,
and share information with other
people in your workgroup or
organization. You can use public
folders to share files or post
information on an electronic bulletin
board.
I'm not sure how effective the tools for managing those "lists" are - I'm not sure if you can mark responses such that all users see the mark, for example.
But it is probably a good start. As people start to see the value of collaboration, something along the lines of a Wiki becomes more appealing.
I've got to say that Confluence, especially now that editing with Open Office or Microsoft Office tools is possible really deserves a look. Not free (as in beer).
I would think a locally hosted php-bb (or other...) forum would be a good choice, as you could moderate it and have a FAQ and history that people could check before duplicating suggestions. So, that's the advantage over a simple email address, and it has a simple, known interface.
What's too complex about Uservoice? The main UI is a single question ("I suggest you ..."). Your users can be anonymous, one field to enter, web based, free for small users. Seems to tick all the boxes except the visual editor. Even administering it is not terribly tricky. (I use it for my iPhone app.)
It looks like you're facing a very standard tradeoff - you want your feedback to be structured, but you don't want any impositions upon your users.
You can't have your cake and eat it too. Why is a wiki off the table? Wikis were designed to balance this kind of tradeoff.
You could use Google Documents to create a shared spreadsheet. Your uses will need Google accounts, but they only need to log in once and a cookie will remember them for next time.
Hum, I've found that we've also InfoPath as part of our toolset. I've never use it, but maybe that it could do the job.
How about using for example Google groups? I've found a mailing list works quite well for this kind of purpose.
Edit: or how about http://getsatisfaction.com/
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 11 years ago.
An obvious answer is "an internal wiki". What are the pros and cons of a wiki used for software documentation? Any other suggestions? What are you using for your software documentation?
Loren Segal - Unfortunately we don't have support for any doc tool to compile information from the source code comments but I agree it would be the best way to store technical documentation. My question was about every kind of documentation tho - from sysadmin type to user documentation.
That's a very open ended question, and depends on many factors.
Generally speaking, if you use a language that has good documentation generation tools (javadoc, doxygen, MS's C# stuff), you should write your documentation above your methods and have your tools generate the pages. The advantage is that you keep the source of your text alongside your code which means it is orgnanized in the logically correct place and easily editable when you make a change to the behaviour of the method.
If you don't have good doc tool support or don't have access to source code, wiki's aren't a bad idea, but they're a second choice to the above.
Note: I'm talking only about code documentation here. Other artifacts obviously cannot be stored alongside code-- a wiki is a great place to put those documents. Alternatively if you use some CMS you can simply commit them in some docs/ folder as text/pdf/whatever files to be editable via the repository. The advantage there is that they stay with the repository if it is moved whereas a wiki does not (necessarily).
Tools are important, but don't get too bogged down in finding the magic tool. No tool I've found yet has a "document everything magically using tiny invisible elves" tickbox. :-)
A wiki will work fine. Or Sharepoint. Or Google docs. Or you could use a SVN repository. Hell you could do it with pens, notepaper, and a file cabinets if you really really had to. (I really don't recommend that!)
The big important key is you need to have buy-in throughout the organization. What happens in a lot of shops is they go and spend a bunch of time and money on some fancy solution like Sharepoint, and then everyone uses it religiously for about two weeks, and then people get busy with hitting the latest milestone and that's the last anyone hears about it.
Depending on your organization, field, the type of products your developing, etc., there are a few solutions to that, but one way or another you need to set up a system and use it. Appoint someone the official documentation czar, give them a cluebat, and tell them to hit people in the head everytime they say "oh yeah, I'll finish documenting that next week...". if that's what it takes. :-)
As for tools... I'd recommend Confluence by Atlassian. It's a fine wiki, it's designed to work in an enterprise environment, it has a lot of nifty features, it's customizable, it integrates well with some of the Atlassian's other nifty tools, and is basically a pretty solid product.
«Software documentation» is a very general term. There is «End User documentation», «Developer documentation», «QA Documentation». First one is usually developed by qualified techwriters. Other ones may be dynamically formed from wikis, documentation comments from source code etc. All this stuff maintenance process usually is very complex and each software company follow its own way. But there is one necessary point for all these ways: each code commiter, architect, manager, qa engineer MUST store well arranged each piece of information which may be helpful for the others. And someone else MUST keep an eye on this pieces storage and rearrange pieces if required. All this steps greatly improve all activities related to development process.
Assuming you are talking about code documentation versus user documentation, an internal wiki is great if you do not need to distribute the documentation for the code outside of your organization, to contractors or partners.
Javadoc or DOxygen is more suitable if you want distributable code documentation.
If you are referring to user documentation, you may want to have a look at DITA.
I started experimenting with a way to do user documentation with these goals:
Markdown/Html/Javascript/file-based relatively linked documents for portability (can run on local file system or you can throw it on a webserver), built-in handling of screenshots (interactively resize), and open source in case anyone else may want to do something with the crazy thing.
Your document source is written in Markdown and rendered to Html via Javascript at browser runtime.
Mandown - http://wittman.org/mandown/
We currently use inline documentation parsed by an external application (PHP + PhpDocumenter) plus various internal wikis. At times it's painful at best (mainly because only one person update the wikis or the docs...)
However, I've been looking at using ikiwiki to do internal docs. It integrate with your source countrol system (including Git, Subversion, Mercurial, Bazaar, TLA and Monotone) so all your docs track with your project. It is built in Perl and has an extensive plugin system (including multiple markup languages, with the default being Markdown). Also, the source control system is plugin based, so if what you use isn't immediately supported you could add your own. In your preferred language, if need be, since it supports non-perl plugins, too.
My company uses a variety of Sharepoint and a wiki. Sharepoint for specific documents like requirements, presentations, contracts, etc, while the wiki is used as a help guide a developer repository for tutorials on using internally developed libraries.
Yeah, we use a wiki, we also use Google documents. I find that Google documents is better than most wikis I've tried and, if you don't need to track all changes, you lose nothing. Google docs provides a good collaboration framework.