3

Let's say I have a complex software product about which the information or knowledge is scattered all over the organization that built it. There are requirements and features about which even the Quality Assurance/Testing department is not very sure.

There are also many facets of the same generic software product and the product gets continuously customized as per the customer's business requirements. Moreover, when you try to explore the software hands on, then often tend to get lost due to its complexity.

What I precisely want to know is how can one document the end user guides as per the aforementioned scenario.

Maxood
  • 1,503
  • 2
  • 11
  • 19
  • 1
    Possible duplicate of [How to manage and estimate unstructured requirements received from customers](http://softwareengineering.stackexchange.com/questions/171295/how-to-manage-and-estimate-unstructured-requirements-received-from-customers) – gnat Jan 07 '17 at 14:49
  • @gnat That duplicate question you are referring, has nothing to do with "Software Documentation". That one was about Software Requirements Management. – Maxood Jan 07 '17 at 15:04
  • 2
    Documenting such a software is easy, compared to the task to maintain it. But honestly, your question is way too broad to be answered here (and it is not even clear what kind of documentation you have in mind, end user docs? Docs in form of written requirements? Developer docs? Something else?) – Doc Brown Jan 07 '17 at 15:05
  • 2
    Start to write the documentation. If the information is scattered through the company, you need to talk to a lot of people. And most important, establish a process where the documentation is kept up to date with every change. I don't think you will get a more specific answer as long as your question is not more specific. – Doc Brown Jan 07 '17 at 15:51

1 Answers1

4

Try to convince your manager or whoever came up with that task that it is not a good idea to write end user documentation for software that is in such a shabby state. It will even increase technical debt because you create another document that is going to have gaps and contain errors from the beginning and that needs to be kept up to date with the software.

In the long run it will be cheaper to document the requirements of the software first, define test cases, implement automated tests and refactor where it makes sense. With reasonable requirements and change management it will be much easier to write end user documentation and keep it in sync with the software.

If this is not an option, talk with some key users and find out how they are using the software, document their use cases, add some diagrams showing the main modules of the software as far as it is obvious, paste in some screenshots, explain input and output files as good as you can. You will end up with a document that at least looks like a user guide and might even be somewhat useful for a limited period of time. But make sure that you are not the person that will be responsible for maintaining the document.

In some cases this really is the best option because end user documentation has a very low priority from a business point of view in many software projects. This is because it tends to have little influence on project success.

Frank Puffer
  • 6,411
  • 5
  • 21
  • 38
  • 1
    Your answer is not bad, but it misses IMHO one point: the "key users" of a complex software are not necessarily the ones who know what is really going on inside the program. There may be other people in the organization, like senior developers, analysts, domain experts, who know this much better. He should also talk to them. I would also expect that certain questions can only be answered by looking into the code base. – Doc Brown Jan 07 '17 at 20:36
  • @Frank Puffer I value your answer and the solutions that you have stated in the 3rd paragraph. Why do you suggest for use case and why not user stories? Moreover, what diagrams are better for the described scenario: Flow Charts, Functional Decomposition Diagrams or Mind Maps? And why? Again thank you for your valuable answer. – Maxood Jan 08 '17 at 10:17
  • @DocBrown: He wrote that the knowledge about the software is "scattered all over the organization". Therefore it would probably be time consuming to talk to all experts. If I have limited resources and my job is to write a user guide that does not need to explain the internals, I would pick a few experienced users to gather information. – Frank Puffer Jan 08 '17 at 21:24
  • @Maxood: What you will get in the first place (when talking to the users) are probably user sories. But for creating the documentation you should probably structure them into use cases. What type of diagrams to use, possibly no diagrams at all, strongly depends on the type of application. – Frank Puffer Jan 08 '17 at 21:30