Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I'm a technical writer tasked to document a rather complex WPF/WCF .net application for a governmental agency. I'm not sure where to start and would like some suggestions from .net developers about what information I ought to capture. If you were a .net/WCF developer and you were brought into a massive custom .net application using WCF, what information would you need to be able to figure out how to use and customize or extend the system? The application, when finished, will consist of:

  • a client app which is available on each machine of an AD authenticated user
  • a variety of web services which are run on a machine IIS
  • one big SQL database which contains the data for the records created by the system
  • calls to third party applications available elsewhere which will be called by the main application.

This is a multimillion dollar custom application with lots of hands touching it and lots of developer hours. It also involves a lot of stakeholders and financial transactions.

The purpose of my documentation is to document the application system for future developers who are new to the project or support personnel who have to figure out what's not working. We already have a technical writer who is documenting user behavior and typical user behavior, so I don't need to cover that.

The developer lead explained a little about the system itself and how the dll's on client and server app talk to one another. He also said that the dll's themselves are compiled code that by themselves they aren't interesting. He also explained that there is a data abstraction layer (called "entities framework"??) which the developers will reference in Visual Studio (instead of incorporating SQL queries in their code). Because of this data abstraction layer, the lead developer seems to feel that documenting the DB tables is not useful (which makes sense). Instead I need to document the service components at a fairly high level.

Now my question: what sort of information should I be capturing? What sort of information would help experienced .net developers learn how to develop for a new application? What sort of questions should I be asking the developers to get this information? I am not a developer (and certainly not a .net developer), but I've worked with several programming languages and documented several Windows apps. The manager who assigned this task to me must feel that the app is not well-documented (even though I've found a lot of UML diagrams and diagrams by business analysts which document business processes. My main audience for whatever I produce will NOT be system administrators or users but other developers.

So do you have any ideas or tips for me? Thanks.

share|improve this question
add comment

migrated from stackoverflow.com May 6 '11 at 15:48

This question came from our site for professional and enthusiast programmers.

1 Answer

By reading your description I'm somehow afraid that one person simply cannot prepare satisfying documentation for such project unless developers already carefully comment their code by standard documentation comments. This is first step to allow new team members to use existing code base. Another step can be providing complex set of unit tests which will show supposed usage of existing code base and also handle regression issues introduced by new code created by new developers.

The feature you described as data abstraction layer is most probably Entity Framework - standard part of .NET Framework since version 3.5 SP1. I don't fully agree that describing the database is not needed unless your colleagues use Entity framework in the way that it generates database for them. If they define database manually (database-first approach) the database should be described as well. When using Entity Framework you can still execute SQL commands directly and in fact you will do it sometimes to optimize performance of your application. Also databases generated by EF don't contain additional indexes for tuning performance.

Now what should your documentation include:

  • Basic overview of the application, its purpose, user roles using this application. It is very important for new developer to understand how is the application used. This should be short introduction.
  • Requirements description. This is generally analysis of your project dependent on the process how your application is developed (waterfall, RUP, agile). It can consists of Use Cases, Requirements, Features, User stories with acceptance criteria, etc.
  • Architecture overview describing main blocks of the application and supposing deployment. It is important to understand physical boundaries.
  • Component diagrams - main components should be described by diagrams showing their interaction and dependency.
  • High level code architecture can be described in well known terms (for example by used patterns).
  • If the application contains some complex algorithms or processes (including some complex communication maps for calling web services) you should describe them by diagrams (use UML diagrams)
  • You can include general requirements for web services - transport protocol, security, etc. (they should be already as requirement in analysis) but the main description of web services should be available as WSDL + XSDs (WCF services can generate this automatically) so it doesn't need to be included directly in documentation and can be only referenced.
  • Document any non standard approach, hacks, workarounds, etc. (small should be documented directly in the code, large conceptual hacks and workarounds should be mentioned in the documentation). Also document advanced approaches.
  • Document tools, frameworks and API used to develop application (including version).
  • Very carefully document how to prepare developer machine so that developer can work on the application - this is generally how to deploy application on the development machine, what are prerequisites, how to get source codes, how to configure everything to work, etc. If the deployment doesn't cover only developer's machine describe rest of steps as well.
  • Optionally document non standard conventions and policies (check-in policies, code quality, code metrics, etc.) required in the code.

If you have complex analysis and design you probably already have most of these done but they must be up to date.

share|improve this answer
    
+1 You answer almost makes me cry. –  jgauffin May 6 '11 at 11:28
    
Ladislav Mrnka, great ideas. (By the way, this project already has 2 business analysts who have mapped out the requirements, with user stories and use cases). Just one question. How do I get to know the main components of the system? What question can I ask (other than "what are the main components of the system?") that might make the developers tell you? What I'm dealing with a gigantic complicated beast, and it's hard knowing where to get started. –  idiotprogrammer May 6 '11 at 13:41
    
If the system is so big there should be some architect / developer who have high level overview over the whole system and he should help you with that. Otherwise you will have to go through the whole analysis and understand the product yourselves. You are writing documentation for developers and such documentation should be written by developers who did the application. –  Ladislav Mrnka May 6 '11 at 13:48
1  
Postscript 2 years later after gig ended). I eventually did hook up with an architect who provided the overview I needed -- although he admitted that in many ways he was as removed from code as much as I was. Many developers felt that most API info could easily be accessed by Studio, so a tech writer wasn't really needed for that. I ended up writing a "novel" which summarized business functions and logic and concepts which a developer or sysadmin or end user might find useful as reference. Example here: robertnagle.info/wp-content/uploads/2012/05/… –  idiotprogrammer May 22 '13 at 4:01
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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