Technical Documentation for Scoped Application

[Ronak3]

Hi All,

Can someone help me out how to do the Technical documentation of the Project. I recently did a Scoped application project and i have to do the Technical documentation / Admin documentation. I was just wondering if the doc would be different for scoped apps or same as for normal projects. 

I want some templates so that i can follow to complete it. Also some suggestions on how to prepare a good documentation. 

[Uncle Rob]

Check out this video, especially the last couple minutes.

https://www.youtube.com/watch?v=wvUPn6c-Hj8

If the solution you're deploying is in scope, I'd just say "here's the properties of the scope we created", along with all the other objects you built that are data strcuture, UI, or logic based.

[woodyfairley]

Excellent video Robert, well done! The document we get to glance at 3:47 looks fabulous, much better than my text files (I was a scary bleeding edge novice in the 70s and 80s, young, dumb, and unafraid). Any chance I could coax you into posting a thread with the topic heading of "Technical Documentation Best Practices" ? I would be willing to contribute a blank Microsft Project Plan file, and some blank text files for business rules, ui policies, styles, etc. Thank you for your contributions to the community!

Kind Regards,

Woody

[woodyfairley]

To learn "in depth" more about documentation, I recommend researching the words agile technical documentation but in the meantime, here is my position and the best help I can offer in a single post (this topic is worthy of many different phd dissertations).

The guiding principle I use when fabricating my technical documentation is this: pretend that after my departure, the hired replacement is less experienced than me and has to re-create the scoped application from scratch, so whatever he or she would need, that is what I have to produce. The list of artifacts will look something like this:

• Customer requirements, usually in the form of a paragraph describing the customer’s desired collection of behaviors and functionality presented in the application. This gets decomposed into a bulleted list.
• A specification document for each custom object (e.g. business rule, UI policy, client script, table, every field, every form view, etc.) the document provides enough detail that a stranger of junior skills could re-create it without help. Include the script.
• Look at the bottom of the Studio screen and it will state how many “files” are contained within the scope of your app. This is how many re-creation documents you should create as part of the development process.
• Guiding principle: documents should assume that a developer with less skills than you may have to re-create your scoped application from scratch using the technical documentation you provide, without your help.
• I personally use a combination of screen shots in a MS PowerPoint slide deck, with notes, combined with a text file describing the choice selections used to create the file AND THE SCRIPT, see the attached screen shots.
• During the development and testing phase it is easy to refine the technical documentation and also produce the user documentation, such as quick reference guides, white papers, and classroom training materials.
• I also create a series of screencast videos that demonstrate the form being filled out field-by-field, including the before and after results. They get published on a web-based training website, or shared via a network share, so the users have easy access.
• I also try to anticipate some of the anomalies a user may experience, for example trying to navigate away from a “dirty form” (i.e. data that has not been saved, a box pops up saying are you sure you want o leave with save and discard buttons).
• Another anomaly may be lost internet connection (and what to do).
• Ultimately, your technical documentation is reference material for the newly hired developer (in your absence); the web training material is for the newly hired users. Together, this collection of artifacts gets packaged with the update sets and the whole thing is then your application. The reality is this: you may be the one re-creating your own scoped application, so ask yourself what technical documentation would best help you?

Generally, a lot of well-intentioned people produce their own tutorials about technical documentation, which reinforces the need for our senior colleagues (Forum Level 5, roll call please) to produce a prioritized checklist that junior developers like me can use as a reference standard for "best practices in technical documentation for developers". It may already exist, but I did not find it when I searched the community. This is not a criticism, as the Forum Level 5 crew continue to demonstrate superb cameraderie in their daily posts of solutions to our desperate pleas for help. My hat is off to every one of them, also the Forum Level 4, 3, 2, 1, and other new members who feel the conviction to contribute. I will always be grateful, and look for ways that I too can contribute.

Kind Regards,

Woody

[Martina Erin]

Whenever I need to write Technical documentation I try to stick to a strict order of things. For me it is more convenient to organize my documents immediately so I use software like docsie.io in order to prevent my docs from losing logical order. The best thing to do is to start with a bulleted list and go on with requirements, specifications and details. It is also possible to include guides or even manuals as long as they are comprehended without difficulties. The main thing is not to overflow your document with excessively detailed information as it may affect the reader`s ability to understand the text.