1 2 Previous Next 19 Replies Latest reply on Jul 22, 2016 4:56 PM by philmodjunk

    Creating developer documentation

    vincedubeau

      Hi All,

       

      I been asked to create developer documentation for a Filemaker solution. The purpose is to provide complete documentation so that a new developer won't have to spend hours trying to figure out the solution. I know know tools like BaseElements can provide a comprehensive look at a Filemaker file but the client wants something in hardcopy so to speak.

       

      I am attaching a Word documentation and a PDF of an outline. I would welcome any comments and suggestions form my fellow FM developers.

       

      FYI, This not something that I developed so I'm looking at it with "new eyes"

       

      Thanks

        • 1. Re: Creating developer documentation
          schamblee

          Do you have the Advance version?  If so create Database Design Report (DDR) 

          If not then I recommend upgrading to the Advance version.

          • 2. Re: Creating developer documentation
            vincedubeau

            I have FMPA and I am using the DDR. I was looking for suggestions on the document content.

            • 3. Re: Creating developer documentation
              wimdecorte

              I would push back hard on the "hard copy" aspect of it.  Unless the client is ok with the HTML DDR as schamblee mentions.  Something like a BaseElements analysis or Inspector Pro analysis is better than any Word document that you can put together.  And is going to be cheaper to generate.

              • 4. Re: Creating developer documentation
                vincedubeau

                Unfortunately they insist on having user readable documentation. While I don't have a problem doing it despite the hard work I quoted a fairly outrageous price figuring they would think about other alternatives. They want what they want and are apparently willing to pay through the nose for it.

                • 5. Re: Creating developer documentation
                  beverly

                  Then written documentation to supplement the DDR (and possibly other analysis).

                  I like to print to PDF all table/fields and scripts, in addition to DDR. These are more quickly searched for what I need.

                   

                  I created HTML files as a "help" for each layout (the elements, the flow, the functionality) and these are printable as pdf (or printer).

                   

                  beverly

                  • 6. Re: Creating developer documentation
                    BruceRobertson

                    I create HTML files as a "help" for each layout (the elements, the flow, the functionality) and these are printable as pdf (or printer).

                    I'd be interested in hearing more about how you do that! It would be great to see an example if you have one you can share.

                    • 7. Re: Creating developer documentation
                      beverly

                      I had small graphics (like emulating the buttons, for example) with text describing what would happen when clicked. Then anything like required fields would be noted. Fairly simple, but easy to link to menus for the different help topics (layouts/reports) and a link on the layout took the users directly to that section (in a web viewer and/or open in browser). Stored in a folder with normal HTML, CSS and a little JavaScript. Just any layout and describe the elements and what's expected. HTML allowed the graphics that would not be allowed on a Text-only based help description. It allowed new people to quickly learn what was there. Sorry, I can't show you examples (proprietary).

                       

                      beverly

                      • 8. Re: Creating developer documentation
                        MarcDolley

                        In the past, I've added context-sensitive help systems to placate clients who wanted written documentation. It's really easy to set up. Add a help table to your file with a few fields including a key, area, topic and description. In one case, I added a container field for a screenshot and a second container field for a movie.

                         

                        Next step is to create a single, very simple script which opens a new (smaller) window and searches for the key you send via a script parameter. Then you can put help buttons (usually just a small question mark) in relevant locations and make those buttons run your help script with the parameter. The end result is that the end user can write their own help system based on their procedures.

                         

                        In your case, you could also create a printable version of the help table data, sub-summarised by area and topic. They'll probably never print it, but at least you will have fulfilled their request.

                         

                        Marc

                        • 9. Re: Creating developer documentation
                          coherentkris

                          Some documentation is good but follows the law of diminishing returns.

                          The more comprehensive the documentation the more costly it is to maintain.

                          Your benefactors need to know that any good FM developer to follow you would benefit more from knowing the business process and problem domain (the why of the design decisions in the solution) than have a external schema document. Any competent developer can get all of the details from the solution itself.

                          • 10. Re: Creating developer documentation
                            wimdecorte

                            Fully agreed with coherentkris

                            The specs / use cases are more important because they describe what *should* happen.  And perhaps an ERD.

                             

                            The solution itself can be documented by running a BE analysis (or other tool) which is the first thing that any FM developer would do anyway instead of reading the document.  I know I wouldn't give it much consideration.

                            It is likely to cause confusion and aggravation if it is not kept up to date.

                             

                            The only thing I would want to see documented is any naming conventions.

                            • 11. Re: Creating developer documentation
                              philmodjunk

                              My current job came with a "Winchester Mystery House" database solution. It's had stuff "bolted on" thru many years and versions. When you pop the hood on any given subsystem, you never no what crazy stuff you'll find.

                              I've just added a context sensitive help system so that I can help users get up to speed on the new features as I remodel as well as brief entries documenting any non-obvious design changes in order to keep my fellow developers up to date.

                              The trick that I wanted to share here is that the help window shows a list of titles to click to open a "topic". Full access users see a list of titles for both users and developers. General users only see the topics for users.

                              Thus, I can use the same tool to doc both how to interact with the UI and also how it is designed.

                              • 12. Re: Creating developer documentation
                                beverly

                                for those of you don't know the Winchester reference:

                                * Welcome - The world famous Winchester Mystery Houseâ„¢ in San Jose, California, is an extravagant maze of Victorian craf…

                                it's a real hodgepodge of construction night-mare!

                                 

                                beverly

                                • 13. Re: Creating developer documentation
                                  philmodjunk

                                  That (regrettably) exactly describes the database that was handed to me when I started work for my current employer. I actually find scripts that use things like:

                                   

                                  Copy/paste instead of set variable/set field

                                  Looping thru portal rows to work with related data

                                  Layouts that allow/require users to directly edit (in an edit box) foreign key field values and even (gasp) primary key fields

                                  As well as numerous design features that use "brittle" methods that "break" when simple changes occur such as personnel turnover or transfers.

                                   

                                  It keeps me busy retrofitting since I usually end up fixing a dozen other things that I find in the process of making the original change or fix....

                                   

                                  The documentation trick that I described makes it very easy to leave notes for myself and my team members so that I improve both the design and its associated documentation.

                                  • 14. Re: Creating developer documentation
                                    beverly

                                    my mantra (after 'backup, backup, backup')

                                    is 'comment, comment, comment'

                                     

                                    1 2 Previous Next