-1

Hie guys. I have never been employed in the software development industry and when I do projects I usually just draw non-standard diagrams or used use case diagrams and class diagrams. This time a company wants me to develop a software for them and they say they want full documentation(e.g SRS, SAD, SDD mock-up etc) of the software.

I tried to google some documentation but I only got nothing useful. Books are too theoretic or do not get deep in this. When I browse projects on github there is just source code and no documents. So I would like your help in writing professional documents of software project.

Most importantly, if anyone has a project that is well documented that you would like to share I would be grateful.

Thank you.

  • 1
    A request for a project is going to get closed, as it is not on topic for this site. Are you asking whether documentation should/can go in github? What exactly is your goal here? – Gort the Robot Mar 13 '16 at 21:28
  • 2
    Unfortunately, recommending sample projects is off-topic here, and there is no one true way to document everything so we can't give a useful answer on that. Your best bet is probably to ask your company for examples of whatever it is they want, since it's likely to differ from whatever "the norm" is even if there is a norm for such things. – Ixrec Mar 13 '16 at 21:28
  • 3
    The majority of open source projects are also written by people who don't care much about documentation; but even if you found a project, Im not sure it would necessarily be good to use that as a reference. Everybody has different expectations of what "full documentation" means; In your situation, you need to to ask the company directly and ask them to specify precisely what information they want included within the documentation. Instead of guessing, you need to make sure they communicate their documentation requirements to you clearly, and clarify anything you're not clear on. – Ben Cottrell Mar 13 '16 at 21:28
  • Sorry guys for the unclear question i have made changes. @Ben Cottrel they are not very good with software engineering stuff but they say they want a software requirement specification, software architecture document, software design document, wire frames and software testing specification. As for how to representation the information they say follow the standard, which is why am asking for your help on how to write the documents in a standard way. – Minathe Mar 13 '16 at 21:44
  • 2
    What are the company employing you to do? if they are employing you to write a Requirements Specification, that implies they have not even yet tasked you with a clearly-defined set of requirements; which should be alarming to you if you've been hired to write code. If you've been hired to solve a problem, then you are a long way from design or code yet. Your biggest problem may be nailing down your requirements, specification, managing the expectations of your employer, and potential end-user(s). In other words, you have a project management problem; not a programming problem. – Ben Cottrell Mar 13 '16 at 22:22
2

This is hopefully a question a lot of developers/engineers ask.

The IEEE maintain the Software Engineering Body Of Knowledge (SWEBOK) v3 which is a good place to start but it won't help you to jump into the templates/documents you need. Instead it will help serve as a high level reference during this process.

Early Answer

Start at this Wikipedia page and note the links such as the one on the IEEE Guide to Software Requirements Specifications and ignore any of the commercial links (I don't trust them).

Then continue browsing the IEEE templates, guides and specifications in all software engineering areas. It is worth looking into these and they will provide you will the most definitive information.

Be warned that there specifications etc. are very full with detail, and designed for people who have studied in that area for a while, but one can ignore sections that are not applicable.

Note that if you search for examples, i.e. SRS examples are out there, unfortunately they often are specific to the software, audience and needs of the organisation they were written for. They won't help provide you with relevant information and serve as references at best.

Continued..

SWEBOK advises us that;

The adequacy of documentation is judged by different criteria based on the needs of the various stakeholder audiences

So when they say they want an SRS or a SDD the content will depend highly on their expectations and needs. But the most important thing to keep in mind is the goal/purpose of each document.

But what do they mean by full documentation?

  • software requirements specifications
  • software design documents
  • details on the software engineering tools used
  • software test specifications and results
  • details on the adopted software engineering methods
  • problems encountered during the development process

These are just some of the deliverables you would start with. You might then add or remove or provide basic or complex documentation in some areas to satisfy the clients needs.

What is good documentation?

It will be good if it conveys the right information to the right people.

It would be helpful to clarify their expectations, and especially find out their motivations, in order to provide them with useful information here. There is nothing worse than documentation that is irrelevant or cannot be used.

It may even be possible that the happiest documentation for them does not fall in line with best practice guidelines. This would make things harder for you, require negotiation but is sometimes a real world concern depending on who you are in this process with.

  • Thank you for the great response I will definitely research more – Minathe Mar 14 '16 at 0:59
1

This subject is so vast that nobody on this site knows finally what you need to deliver to your purchaser. But I would like to share some thoughts.

Try to find out what your purchaser's intention is, this is also what Ben recommends in his comment. Why? Because different expectations will force you to behave completely differently. Here is what your customer could say:

  • "We want to understand what you are doing. We want to learn with you, while you develop."
  • "We want to see the project is developing in a formally proper way."
  • "Once the project is finished, somebody else will continue to develop and therefore needs the documentation."
  • "We have heard it is important to have a documentation."
  • "We are now a ISO XY company and in paper 8763874.8734 there is written that projects of type A77 must be documented."

These are totally different situations. Be prepared to have a strategy for such intentions.

If you have formal requirements (like ISO), then you must be given the final documents that instruct you how to proceed. If somebody else continues after you, try to know this person as early as possible, and to adjust the process and the outcomes.

Find out what is also important to your customer. Is it important what tools you use? What if the people simply know the Office suite and expect you to draw UML diagrams with Word? Do you have to recommend a software design product? If you talk to your employer in UML, will they understand or do they need a simplified presentation with Powerpoint?

Are people aware that the Agile Manifesto says, "A constantly working software is more important then a comprehensible documentation", look here: http://www.agilemanifesto.org/

It is written there for a reason. Documentation is expensive. It binds resources. It tends do get outdated. It makes you sit there for hours, maintaining lists and diagrams while the bugs are not getting fixed. Do they pay you for that? As you say you have not much experience, who will pay the learning curve?

"Stick to the standards". Ok. Standard is something very different for a big company than for a small company. But maybe they mean "well established tools and methods in Software Engineering".

So here is what I would do in that situation (all documents as short as possible and as long as needed):

  1. A document with user stories. This can be free text. It is important that the users see their daily work reflected in there.

  2. From user stories, you derive UML use case diagrams.

  3. From use case diagrams, you derive listed and numbered requirements and suitable, matching test cases. You will need them later.

  4. From use case diagrams, you derive analysis diagrams. There, you show by symbolic and strong formal diagrams how the customer's world is running. Not how the software is built, this is the subject of design.

  5. Transfer the analysis diagrams to software design diagrams. Could be: ERDs, class diagrams, component diagrams, call graphs, state diagrams with swim lanes... Here you go: http://www.uml-diagrams.org/uml-24-diagrams.html

  6. From the software design diagrams, start implementing test cases and and productive code, continuing tested by the test cases.

  7. Grab a Doclet tool, write good headers in the code and create an HTML documentation from the headers.

Well, that should do it. Try to work out crucial mechanisms and focus on them. If the company was bigger, more documents were added - concerning security, safety, risk analysis considerations, performance and availability considerations. Would your customer like to see a physical component diagram with balanced nodes? Don't forget that every artifact (document, piece of code) should have a clear number, to avoid misunderstandings due to version cluttering. Where does your customer draw the line? Is it important what code repository you use?

You have mentioned "Wireframes". They are a part of the user interface design, or prototyping. Have a look at these: https://balsamiq.com/products/mockups/, https://uxpin.com/, https://moqups.com/ Working with prototypes are a good thing. It drastically reduces costs of late corrections. The prototype is adding to the user stories, saying "this is how the customer would like to handle the software visually, physically". -

If everything goes well, you will end up with a tested software, a UX façade and a handy collection of sheets. If you are to handle issues after, you can start the chain: The issue alters the user stories, which alters the use case, which alters the ... ...

But I must not make you false hope. If you never learnt to handle for instance Astah or something similar, you will need a lot of time just to understand what those tools can do for you. Also, you have to get used to many details of UML specific notations. Maybe it is a good thing to inform the customer clearly that you are learning, and you do appreciate the opportunity to learn, but both parties must be patient.

  • Thank you very much you really provided useful information. For the why part this is the response : Its a manufacturing company that has been outsourcing all of their software projects but now they are planning to open a software engineering department by the end of the year to reduce cost hence the need for the documents for whomever will be in charge of the project in the future. – Minathe Mar 13 '16 at 22:56

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