Win a copy of Emmy in the Key of Code this week in the General Computing forum!
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Liutauras Vilda
  • Junilu Lacar
  • Jeanne Boyarsky
  • Bear Bibeault
Sheriffs:
  • Knute Snortum
  • Devaka Cooray
  • Tim Cooke
Saloon Keepers:
  • Tim Moores
  • Stephan van Hulst
  • Tim Holloway
  • Ron McLeod
  • Carey Brown
Bartenders:
  • Paweł Baczyński
  • Piet Souris
  • Vijitha Kumara

What are the release documents

 
Greenhorn
Posts: 6
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi,
I want to know if i am releasing the software what are the mandatory documents i should also be releasing like Test plan etc.  Can i get a list of all docs.
 
author & internet detective
Posts: 39574
781
Eclipse IDE VI Editor Java
  • Likes 2
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Vihaan,
Welcome to CodeRanch!

This is going to vary by company and/or project.
 
Vihaan Reddy
Greenhorn
Posts: 6
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thank you for the reply. Right now i am establishing the software process for my company which is a kind of start up. I am basically working on embedded products which involves micro controllers, where i can look for the release process documents or the complete life cycle documents. Please advise.
 
Jeanne Boyarsky
author & internet detective
Posts: 39574
781
Eclipse IDE VI Editor Java
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
In a start up, you probably need less documents.

Think about what you already do and what you would need for support. For example, do you have any requirements or design documents? Do you have a user manual? What will your users do if they have problems? What would you need to reference?
 
Saloon Keeper
Posts: 21212
136
Android Eclipse IDE Tomcat Server Redhat Java Linux
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Here's my standard set, based on one former employer who got their inspiration from Oracle and Rational:

1. Executive Summary - 1-2 page overview on what the system is needed for, its stakeholders, its basic shape and how much time/money will be required to realize it.
2. Functional Specification - Document outlining the details of the system, including a more complete enumeration of the the features of the system and what it will be expected to do.
3. Implementation Specification - Document paired with the functional spec that describes how the system will operate in order to implement the functionality. This is also the reference document for later debugging and maintenance.

To this, depending on need are one or more documents for stakeholders:

1. Operations Guide - installation and daily operation of the system for the IT staff.
2. User's Guide - reference manual/help system for the line-level users.
3. Application Administrator's Guide - complex systems often need application management functions that require special privileges not given to line-level users. This document keeps them separate from the general user's guide.
 
Vihaan Reddy
Greenhorn
Posts: 6
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thank you very much for the replies. I will post a clear diagram of the process i am following and the corresponding documents in some time from now. Request to please provide feedback on the same.
 
Vihaan Reddy
Greenhorn
Posts: 6
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
This is the understanding document i made from one of the customer requirements documents i had. Am I correct in the understanding?
SwProcess.png
[Thumbnail for SwProcess.png]
 
Tim Holloway
Saloon Keeper
Posts: 21212
136
Android Eclipse IDE Tomcat Server Redhat Java Linux
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Wow. That's the kind of stuff that you'd typically have to deal with in a very large (mainframe-style) shop or doing a government project and typically that's with a large development team and separate testing team. Many of the documents you listed in the places I've worked would be components of the smaller set of documents I enumerated. And I'm used to working as Chief Cook and Bottle Washer on most of my projects, so stuff like formal weekly progress reports were only something I've had to endure once (and it was the worst employer, bar none, that I ever worked for).

If you yourself had to to all of them you'd probably have time to do nothing but write documents, so you should probably get with stakeholders and see what they actually need and also see which ones you can offload onto other people.
 
Marshal
Posts: 14240
236
Mac Android IntelliJ IDE Eclipse IDE Spring Debian Java Ubuntu Linux
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I will speak more plainly, so pardon the cynicism. If your company is a startup and you're planning on doing all this formal planning and documentation of the planning, then you should probably include a plan for what to do when your startup goes belly up.

Startup mode operations are very chaotic. They are experimental and by that, I mean they quickly try things out to see if they work and then inspect and adapt if things don't go quite as expected. The attitude of a startup is that of fearlessness. You have to be willing to fail and learn from your mistakes and you have to be prepared to do this often. The amount of planning you're planning on doing tells me there is exactly the opposite mentality behind that huge diagram.
 
Junilu Lacar
Marshal
Posts: 14240
236
Mac Android IntelliJ IDE Eclipse IDE Spring Debian Java Ubuntu Linux
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Without some knowledge of your context, it's difficult to give specific advice on what documents would be appropriate to accompany a release. As far as I know, most startups don't have much documentation with their releases. It could be as simple as a README.txt file that contains the release notes. That's pretty much the bare minimum you'd expect from anyone who has a decent engineering process. If they're really into providing detailed information, they'd probably publish something on their website to help users navigate through the new features of each release, you know, like user guides and such. If they're even more sophisticated, they might have a section on their website for developers to learn about new ways to programmatically interact with the new release, like API documentation or developer guides. If you're selling the software you're creating instead of just running it and making it accessible to users, then I think you'd also be obligated to provide some of the things that Tim mentioned, like an Operations Guide and Administrator's Guide.
 
Tim Holloway
Saloon Keeper
Posts: 21212
136
Android Eclipse IDE Tomcat Server Redhat Java Linux
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Yeah. When you have that much documentation requirement, it's basically micro-management.

It reminds me of a very large company here in town back in the days when Rational Rose was a "must-have" skill. They had a project with a 2-year deadline. They spent about 18 months drawing Rational stick-figure diagrams and generating huge amounts of cubicle wallpaper, then at the 18-month point, panicked because they were running out of time and slapped out the usual mess.

Meticulous paperwork is a given in government projects, where contractors are constantly trying to weasel their way out of actually supplying value for money, since value is expensive and gets in the way of profit. And, alas, despite all those documents, they routinely short-change their clients regardless.

So if you have a choice, limit the documentation to what's useful. But, to paraphrase Einstein, no less.
 
Vihaan Reddy
Greenhorn
Posts: 6
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Yes after your replies, I am filled with confusion not sure how to proceed. Start up companies are really challenging and headache i think.
 
Junilu Lacar
Marshal
Posts: 14240
236
Mac Android IntelliJ IDE Eclipse IDE Spring Debian Java Ubuntu Linux
  • Likes 2
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Here's something to think about. As a startup, you want to produce as much value as possible for as little effort as possible. Whatever effort you make, it should be towards producing value. What value does all that documentation produce for your users? Is it essential? If you don't produce the documentation, will it hurt your ability to sell the software or the services related to the software? Value and outcomes (making your users happy) is what you should focus on. Creating documents is largely just output, not outcome.
 
Tim Holloway
Saloon Keeper
Posts: 21212
136
Android Eclipse IDE Tomcat Server Redhat Java Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Junilu Lacar wrote: Creating documents is largely just output, not outcome.



Until you end up in hospital and no one knows what's going on. Or for that matter, even want to go on holiday. Or need to remember what you did last year.

You don't need an extensive library of different kinds of documents for this - and in fact it would be counter-productive, since then no one would know where to look. But you should write down something. And, of course, keep it up to date. Outdated documentation is dangerous.



Incidentally, I spent the last couple of days creating Functional Spec docs for clients. I use them to ensure that both I and the client understand the abilities and requirements of the project the same way (as much as humanly possible). It's also their guide to setting up, operating, and maintaining the system I produce once I turn it over to them. It's updated as the project's shape changes. So it's actually part of the product.
 
Junilu Lacar
Marshal
Posts: 14240
236
Mac Android IntelliJ IDE Eclipse IDE Spring Debian Java Ubuntu Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Tim Holloway wrote:You don't need an extensive library of different kinds of documents for this - and in fact it would be counter-productive, since then no one would know where to look. But you should write down something. And, of course, keep it up to date. Outdated documentation is dangerous.


Yeah. Don't get me wrong, there are certainly documents that are useful to have, especially if it helps people get some context around things related to development. These documents should have a well-defined target audience who actually benefit from what's in the documents. What I was referring to when I said "just output" were the "busy work" type documents that have information that changes often in unpredictable ways like Detailed Design Specifications. These kinds of documents are project- and company-killers.
 
Tim Holloway
Saloon Keeper
Posts: 21212
136
Android Eclipse IDE Tomcat Server Redhat Java Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Actually, I'd argue that a detailed design specification is the antithesis of Agile. One of the major selling points of Agile is to deliver incomplete and imperfect and to guide the completion and perfection of the project based on feedback along the way.
 
Junilu Lacar
Marshal
Posts: 14240
236
Mac Android IntelliJ IDE Eclipse IDE Spring Debian Java Ubuntu Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Tim Holloway wrote:Actually, I'd argue that a detailed design specification is the antithesis of Agile.


And you'd have no argument from me about that. As I have said again and again in these forums, I subscribe to the idea that the code is design and that tests are executable design specs.
 
And inside of my fortune cookie was this tiny ad:
Java file APIs (DOC, XLS, PDF, and many more)
https://products.aspose.com/total/java
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!