23

I've been working on a project for a couple years now, and I'm starting to gather a decent user base. I've created a project page with some basic documentation, but it's really not much more than a FAQ at this point. I know that I need to improve it so that it's more informative for both new and power users, and that's next on my to-do list for the next release.

However, the next release has features that the user base is anxious to get. I'm prepared to release it right now, it's packaged and ready to go. I just need to deploy it to the appropriate distribution services.

To the point. The features are important to my users, but the documentation is important to me. Should I wait to release until after I rewrite the documentation? My current user base is savvy enough to understand how to use the new features, so that's not what I'm worried about. It may take a couple weeks to finish the docs, as I have limited free time to work on this project, but the community would roast me on a spit if I made them wait any longer.

Is the customer right in this scenario? Should a fantastic, straight-forward feature for existing users take priority over robust documentation for new users?

Update: Wow, so many great, high-quality responses! You've really helped me get a better understanding of how I should be interacting and supporting both the project and its users. Thanks a million!

Improve this question
6
  • 14
    Yes, the customer is right. Roll out the release, then spend the two weeks getting the documentation in place. You already told us that the user base isn't going to be adversely affected by the lack of documentation, and it's only two more weeks. If this were a real gig, your customer or organization would be roasting you on a real spit, because two weeks without a release is two less weeks to garner market share.
    – Robert Harvey
    Jun 14, 2016 at 2:58
  • 3
    Depending on the project you might release the new version in a separate branch as "beta" or "preview".
    – CodesInChaos
    Jun 14, 2016 at 7:22
  • 2
    What kind of documentation - end users documentation or source code documentation? Or is your project of some kind where there is no distinction between those?
    – Doc Brown
    Jun 14, 2016 at 10:45
  • 5
    There doesn't seem to be any conflict here: if it's packaged and ready to go then why can't you release it and work on the documentation next, for a docs-only update in two weeks? Are you concerned that releasing will generate a lot of work (on reported bugs and so on) that will prevent you working on the docs? The reason you can't do both should be taken into account by answers.
    – Steve Jessop
    Jun 14, 2016 at 11:04
  • @DocBrown In this case, it's user documentation. Source code documentation would be useful only to me.
    – cyberbit
    Jun 14, 2016 at 15:50

7 Answers 7

Reset to default
45

Simple: Release a beta version! Then when documentation is done, do final release of the new version.

If you have users willing to try out the new stuff, then by all means take advantage of that. You will get bug reports, you probably get community questions about the difficult points so you know where to concentrate on the documentation, etc. You may also want to tweak some things based on user feedback, which may affect documentation.

Basically, everybody wins.

One reason to not do early release is, if you think your users will not be receptive of a "beta version", then you should think twice about doing it, but going by what you write, sounds like they would be happy about it.

Another reason would be, if there are technical difficulties about doing a beta release using whatever release channels you use. Then it might be more hassle than it's worth to do separate beta and final releases. If you think your software is complete, then in this case I'd lean on early release, update documentation when it's done. Otherwise there's the risk that the documentation gets delayed, and then the whole release gets delayed or you end up releasing without final documentation anyway, so just do it now.

Improve this answer
6
  • 1
    I have done this in the past for small tools so many times... code is done, it all seems to work, but it's the end of the weekend and I can't be bothered to finish the documentation now. I just package it as a beta release and voila, if you were wanting the new version badly then here it is, otherwise, you'll have to wait for next weekend.
    – Pimgd
    Jun 14, 2016 at 14:03
  • I actually considered a beta release before I asked here! The problem with that idea is that the channels I use force me to write a completely separate app to have split releases. I began working towards a separate beta, but the logistics of it are difficult and it didn't seem worth it at this stage of the project.
    – cyberbit
    Jun 14, 2016 at 15:51
  • Instead, what I chose to do with the feature is make it an opt-in beta in a normal release. This makes sure that people who want a stable experience keep it, and those who want the new feature can use it, with the knowledge that it may break at times. Then, in a future release, I can move the feature from opt-in to integrated, remove the beta designation, and all is well in the world.
    – cyberbit
    Jun 14, 2016 at 15:55
  • 3
    Apache uses "Release Candidates" to mark a project that is functionally complete, but are just validating the package has all the resources and it's truly ready for prime time. Sounds like you are beyond the beta stage (functionality mature but still not complete).
    – Berin Loritsch
    Jun 14, 2016 at 17:29
  • @BerinLoritsch I've seen that used before. That label actually fits well in this case. I guess putting an opt-in feature in a normal release is (in my case) something like a release candidate. It's stable, it works, but it hasn't seen the light yet.
    – cyberbit
    Jun 15, 2016 at 1:07
15

If I got you right, you are doing this project on your free time and for no money. If this is the case, then please, do what makes you feel better (users wait, document on your time). You should not feel the pressure from your "users". Many people wrote about this on the Internet (Large FLOSS authors and contributors who felt the pressure).

But, if you are getting paid, or you get some benefit, please do what your users want. This means do whatever is best for your customers or users, in that case, just release it and document on your time. You said they would find their way around, so it should not be a big deal.

Improve this answer
1
  • You got it right! This is an unpaid gig. But I do get some benefit, as I'm one of the power users I talked about. :P What you say makes sense, though, and I appreciate your answer!
    – cyberbit
    Jun 15, 2016 at 1:03
4

In general there are two types of documentation: the technical which documents your code (classes, units, etc) and how new features may operate and being implemented in the code and user documentation. IMO, technical documentation is a must especially if software development is not your full time job. I spend lots of time on this as I may have large gaps periods of writing code due to life commitments.

User documentation is good to have but not essential I believe. Of course it depends on the complexity of the application, the familiarity of the user base with the use of computers and systems in the subject area in discussion--in your case it looks like your customers can get the grasp of how new features work. There is a school of thought out there arguing that good user experience and good user interface require minimal user documentation.

Also, if your time is limited and you really feel pressure to develop documentation as you suggest, you can make a couple of short videos introducing the new features only. This will buy you some time to write the actual documentation and then you can fill in the less important details.

Some marketing tips may allow you to balance user expectations and still boost your brand. It really depends on the type of application and the workflow you have created so far, but you could have a welcome screen to your new version and within the application you can show the videos either by providing links or by playing the videos inside the app.

Improve this answer
3

Just to add something not only for this specific example but for general workflow:

Documentation might be your definition of done, but documentation is most of the time beyond a minimal viable product (MVP).

Not only is the customer always right. If it is a commercial product, releasing might be a lot of business value and is an absolute priority.

The owner defines the business value (which is you I reckon), so what is more valuable as a product for your customers?

Also are there any risks releasing without documentation?

For example competition; If the competition releases this super-feature before you, you just might lose some users.

Ask yourself or the product owner these questions and your answer will be clear.

Improve this answer
2

New features make old users happy. Good documentation invites new users. Which you should concentrate on depends on which you're more in need of. You indicated the user base was healthy so new features can wait. Speaking as an old user, I like good documentation as well. Nice thing about open source: old users add their own features.

Improve this answer
3
  • 2
    Good documentation only invites new users if it documents something that actually exists.
    – Robert Harvey
    Jun 14, 2016 at 3:00
  • @robertharvey A current user base was indicated. Thus I presume they are using some unreleased beta something or other.
    – candied_orange
    Jun 14, 2016 at 3:06
  • There's an existing release, which from the sound of it is considered stable despite being under-documented.
    – jpmc26
    Jun 14, 2016 at 15:37
2

You have not clarified in your question and probably not to your users the consequences of these choices. How much time are you spending on user support? Will additional documentation decrease the amount of time you spend on support or increase sales? What is the advantage to you to do documentation?

Your users want new features over documentation, but do they realize there could be a decrease in your availability to provide support, fix bugs, release patches, etc.?

If I didn't bother to read the instructions when all I have to do is send you an email with my question, why would I ever want documentation over new features?

Improve this answer
-1

If the package is ready to release, release to customer/client and start work on the documentation. It is good communicate to the client, when you will share the documentation which helps them to understand the deployed features.

Improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.