Stumbled upon: Write the Freaking Manual

I stumbled upon the thread "WTFM: Write the Freaking Manual" triggered by the following blog post http://www.floopsy.com/post/32453280184/w-t-f-m-write-the-freaking-manual.

I would recommend to follow the thread (which already contains more than 200 thoughts) in case you want to understand:

• the different views of the developers
• the different views of users of a certain software
• the different views of tech writers

I also had discussions with companies creating software products what needs to be documented, is it possible to create a software product which doesn't required additional documentation because of "intuitive usability" etc.

The answer is easy and difficult at the same time:

You have to deliver relevant information for your audience.

This means you have to understand:

• What is your audience?
  and
• What is relevant?

 And always keep in mind that  "Your user does not have the same context compared to you".

Example

If you develop a software infrastructure should support other developers to do their job faster you should deliver:

• orientation for your user (which tasks does the library support)
  
  the concept of all major parts of your framework from top to down
  => basic overview of all implemented concepts and than describe each concept
  
  good example is provided by IBM for their ICU library (http://userguide.icu-project.org/)
  This library isn't very trivial but you have well described concepts for all components of the library.
• how-to setup
  provide how-to to setup the software for initial use
• how-to use
  provide as many code samples / demos / real working code for the operation of your user
  e.g. by providing your well-documented unit-test library.

How can you identify which information your audience needs? 

You have to understand their daily operation with your software and all questions which cannot be answered by the software itself without additional information in a short amount of time.

If you identified those areas well the resulting documentation will add value to the software and will increase the audience using your software.

Why, What and How

If you want to define a RFP (Request for Quotation) / RFP (Request for Proposal) or you have to answer those requests you are forced to define or understand requirements for a particular product or solution.

There are lot's of good sources showing how to write and handle requirements. But often they miss one important fact which makes either the creation, prioritization and understanding of requirements much easier. The Why instead of the What.

Rational

1. First set the baseline for effectiveness. (Why)
2. Than define what you need to be effective. (What)
3. And at the end define the efficiency. (How)

What is the rational, the reason for a particular requirement. If you try to understand the Why or if you forced to define the Why the resulting requirements / usage of the requirement are much more valid than without doing this.

The "What" does not tell anyone the real intention of a solution. The why provides the motivation and business value and therefore the baseline for effectiveness which makes or makes not a requirement right to exists.

ToDo

1. Before you start to define any requirement try to define the major "Whys"  you intent to solve. Keep in mind that there must no requirement which cannot be derived from those high level whys.
2. derive each use-case / requirement from one of the major why areas and add a specific rational for the individual use-case / requirement.
3. classify / prioritize the requirements based on the rational.
4. Derive the "How". In this step the statement of efficiency is the key for selection of the right solution.

Result

• The defined requirements are much easier to understand and alternatives can be much easier identified and qualified.
• Prioritization can be much easier coordinated to management because the consequence of a decision for the "Why" and therefore the company / department goals are always clear even if someone does not have detailed knowledge of the subject matter.
  
  =>ensure effectiveness
• Definition of the system requirements / How can focused on efficiency.
  =>ensure efficiency

To see the same idea from sales / marketing point of view watch: Start with Why: How Great Leaders Inspire Everyone to Take Action.

top most dangerous programming errors

the list "Top 25 Most Dangerous Programming Errors" makes clear that the software domain still has much to learn. do you involved in software development projects either as project manager, software architect or software developer? if so you are sure that the mentioned errors not happen in your daily work or the subject of your daily work?

i think it is still much work to do until software development can be called a "proofed engineering discipline".

the more application will be hosted in the cloud the more such kind of issues will be mission critical for the target group of the application.

by the way the list is a good reminder of low level non functional requirements and topics for peer-review....

agil development means valuable end user assistance

gile development methods have become more and more popular during the last few years. Especially the software domain tries to speed up development cycles and deliver new features on demand of the customer. most common method today is SCRUM.
there are many good books, articles, forums and blogs out there describing the goal, advantage of diving into agile software development. but less or zero of them covering the creation of end user assistance, like online help, for the different users groups and additional, required information must be shipped with the product.

#1 principle of agile manifesto

Our highest priority is to satisfy the customer
through early and continuous delivery
of valuable software.

"valuable software" of course means one the customer is able to use, therefore end user documentation is essential part of the software development process.

that means that you have to change your process to

• no more write documents / additional information instead
  write valuable information assigned or integral part of the product component it belongs to
  a document is one potential output if a customer value can be achieved with this type of output
  
• no more prioritize, test, deploy and measure customer feedback for the application and the user documentation as separate applications instead
  while working on a particular feature prioritize, test and deploy all valuable user information and work together with the customer to get feedback for the complete application (incl. user documentation).
  

sounds simple, but as you know that isn't simple at all. many companies currently workaround the mentioned issues or just ignoring the resulting consequences.

by the way one of the few blog posts I found "Writing End-User Documentation in an Agile Development Environment".

what is your experience and solution to this challenge?

• do you discuss end-user documentation requirements while sprint planning / review...?
• do you prioritize end-user documentation along with the corresponding user story?
• do you test your end user documentation while test your application?
• ....?
• do you localize user documentation while localize your application?
• do you use dedicated professional writes or other team members for creating end user related information products?
• ....?